--- name: shadowob description: "Use when live Shadow context or actions are needed: channel/DM history, pins, members, server/channel/workspace/shop/app/buddy data, or sending/managing Shadow content via the shadowob CLI." metadata: { "openclaw": { "emoji": "🏠", "requires": { "bins": ["shadowob"] }, "primaryEnv": "SHADOWOB_TOKEN", }, } --- allowed-tools: ["exec"] # Shadow CLI Use `shadowob` CLI to interact with Shadow servers. Activate this skill when you need current Shadow context, such as recent channel or DM history, pinned messages, member/server/channel state, workspace/shop/app/buddy data, or when you need to send or manage Shadow content. Prefer narrow `--json` reads before acting. ## Quickstart ```bash # Login (one-time setup) shadowob auth login --server-url https://shadowob.com --token # List servers shadowob servers list --json # Send a message shadowob channels send --content "Hello" --json ``` ## Authentication Set token via: 1. `shadowob auth login` (persistent, stored in `~/.shadowob/shadowob.config.json`) 2. `--profile ` to use a specific profile 3. `SHADOWOB_TOKEN` env var (used by SDK directly) ### Profile Commands ```bash shadowob auth login --server-url --token --profile shadowob auth switch shadowob auth list shadowob auth whoami shadowob auth logout --profile ``` ## Servers ```bash # List joined servers shadowob servers list --json # Get server details shadowob servers get --json # Create server shadowob servers create --name "My Server" --slug myserver --json # Join/Leave shadowob servers join [--invite-code

]
shadowob servers leave 

# Members
shadowob servers members  --json

# Discover public servers
shadowob servers discover --json
```

## Channels

```bash
# List channels
shadowob channels list --server  --json

# Get channel
shadowob channels get  --json

# Create/Delete
shadowob channels create --server  --name  [--type text] --json
shadowob channels delete 

# Messages
shadowob channels messages  [--limit 50] [--cursor ] --json
shadowob channels send  --content "text" [--reply-to ] [--thread-id ] --json
shadowob channels edit  --content "new text" --json
shadowob channels delete-message 

# Reactions
shadowob channels react  --emoji 👍
shadowob channels unreact  --emoji 👍

# Pins
shadowob channels pin  [--channel-id ]
shadowob channels unpin  [--channel-id ]
shadowob channels pinned  --json
```

## Buddy Inbox Task Cards

Inbox tasks are ordinary channel messages with `metadata.cards[]` entries where `kind="task"`.
When a task card is assigned to the current Buddy, treat it as an explicit trigger even if the
channel normally requires mentions.

You are not statically bound to one server. Resolve the active server from the current message, Inbox task, or server App command context before calling the CLI. When routing work to another Buddy, do not create ordinary channels as Inbox routes; use that Buddy's Inbox and task cards.

```bash
# Discover or repair Inbox channels
shadowob inbox list --server  --json
shadowob inbox ensure --server  --agent  --json

# Enqueue a task card when acting as an authorized tool or Server App operator
shadowob inbox enqueue --server  --agent  --title "Task title" --body "Task body" --requirements-json '' --output-contract-json '' --privacy-json '' --json

# Claim the next task from a Buddy Inbox
shadowob inbox claim-next --server  --agent  --json

# Claim/update a known task card
shadowob inbox claim   --json
shadowob inbox update   --status running --note "Started" --json
shadowob inbox update   --status completed --note "Done" --json
shadowob inbox retry   --note "Retry after fixing input" --json

# Turn an existing chat message into a Buddy Inbox task
shadowob inbox promote  --server  --agent  --title "Task title" --json
```

Runner contract:

- Read `metadata.cards` before deciding whether to skip a message.
- Accept active task cards assigned to your `agentId` or bot `userId`.
- Treat `requirements`, `outputContract`, and `privacy` as first-class task fields.
- Claim before work, mark `running` while working, then mark `completed` or `failed` with a concise note.
- Reply to the Inbox task message when you need the owner to see a human-readable result.
- prefer Workspace files for shared context and artifacts. Cache Workspace folder and file ids when you create or discover reusable locations.
- Upload final artifacts to Workspace first, then reference them with `workspaceFileId`, `workspaceNodeId`, or a `workspace://path/to/file` URI instead of runtime-local paths.

## Threads

```bash
# List threads
shadowob threads list  --json

# Get thread
shadowob threads get  --json

# Create/Delete
shadowob threads create  --name  --parent-message  --json
shadowob threads delete 

# Messages
shadowob threads messages  [--limit 50] --json
shadowob threads send  --content "text" --json
```

## Direct Messages (DMs)

```bash
# List DM channels
shadowob dms list --json

# Get DM channel
shadowob dms get  --json

# Create DM channel
shadowob dms create --user-id  --json

# Messages
shadowob dms messages  [--limit 50] --json
shadowob dms send  --content "text" --json

# Delete DM channel
shadowob dms delete 
```

## Buddies

```bash
# List buddies
shadowob buddies list --json

# Get buddy
shadowob buddies get  --json

# Create/Update/Delete
shadowob buddies create --name  --username  [--display-name ] [--avatar-url ] --json
shadowob buddies update  [--name ] [--display-name ] --json
shadowob buddies delete 

# Control
shadowob buddies start 
shadowob buddies stop 

# Token
shadowob buddies token  --json

# Config
shadowob buddies config  --json
```

## Workspace

```bash
# Workspace info
shadowob workspace get  --json
shadowob workspace tree  --json
shadowob workspace stats  --json

# Children
shadowob workspace children  [--parent-id ] --json

# Files
shadowob workspace files get   --json
shadowob workspace files upload  --file  [--name ] [--parent-id ] --json
shadowob workspace files update   [--name ] [--parent-id ] --json
shadowob workspace files delete  
shadowob workspace files search  [--search-text ] [--ext ] [--parent-id ] --json
shadowob workspace files download   --output  --json

# Folders
shadowob workspace folders create  --name  [--parent-id ] --json
shadowob workspace folders update   [--name ] [--parent-id ] --json
shadowob workspace folders delete  
```

### Workspace Node Metadata

Each workspace node has a `flags` JSONB field with optional metadata:

- **Access control**: `flags.access = { scope: "server" | "channel", serverId, channelId? }`. All nodes have at least `scope: "server"` + `serverId`. Channel-scoped nodes require channel membership for access.
- **Traceability**: `flags.source = "channel_message_attachment"` with `channelId` and `messageId` for files uploaded via channel messages, enabling reverse lookup to the originating message.
- **Path is server-computed**: `path` is derived from parent path + name, maintained server-side. Do not set path manually — it is auto-updated on rename/move.

## Shop

```bash
# Shop info
shadowob shop get  --json
shadowob shop get-by-id  --json
shadowob shop me get --json

# Products
shadowob shop products list  [--status active] [--keyword ] [--limit ] --json
shadowob shop products list-by-shop  [--status active] [--limit ] --json
shadowob shop products get   --json
shadowob shop products purchase   --idempotency-key  --json

# Offers, deliverables, and shop assets
shadowob shop offers list  --json
shadowob shop offers create  --data '' --json
shadowob shop offers deliverables create   --data '' --json
shadowob shop assets list  --json
shadowob shop assets create  --data '' --json
shadowob shop entitlements list  --json

# Cart
shadowob shop cart list  --json

# Orders
shadowob shop orders list  --json
shadowob shop orders get   --json

# Wallet
shadowob shop wallet balance --json
```

## Commerce

```bash
# Product and offer buyer context
shadowob commerce products context  --json
shadowob commerce offers preview  --json
shadowob commerce offers purchase  --idempotency-key  --json

# Chat commerce cards
shadowob commerce cards list --channel-id  [--keyword ] --json
shadowob commerce cards purchase   --idempotency-key  --json

# Purchases, delivery, protected files, and community assets
shadowob commerce entitlements list [--server ] --json
shadowob commerce entitlements get  --json
shadowob commerce entitlements verify  --json
shadowob commerce paid-files open  --json
shadowob commerce assets list --json
shadowob commerce assets consume  --idempotency-key  --json

# Seller income and support actions
shadowob commerce settlements list --json
shadowob commerce settlements settle --json
shadowob commerce tips send --recipient-user-id  --amount  [--message ] --json
shadowob commerce gifts send --recipient-user-id  --assets '' --json
```

## Commerce Validation Notes

- Use the CLI for setup, inspection, and automation, but validate commerce user stories in the
  browser before calling them complete.
- Do not add seed code to populate commerce surfaces. Create ordinary local/test records through
  browser flows or explicit setup calls.
- When inspecting a commerce flow, preserve ids for the handoff: product, offer, order,
  entitlement, shop, server, Buddy, and workspace file where applicable.
- External app entitlement automation must use Shadow OAuth commerce APIs and remain scoped to the
  app's own `external_app` resource namespace.

## Apps

```bash
# Server App integrations
shadowob app list --server  --json
shadowob app preview --server  --manifest-url  --json
shadowob app install --server  --manifest-url  --json
shadowob app uninstall  --server 
shadowob app discover --server  --json
shadowob app inspect  --server  --json
shadowob app skills  --server 
shadowob app call   --server  --channel-id  --json-input '' --json
shadowob app call   --server  --help
shadowob app call   --server  --file  --json-input '' --json
shadowob app events  --server  --json
```

For server App commands, use the `shadowob app` CLI path only. Do not use curl, fetch, raw HTTP
routes, or the JavaScript SDK to call server App commands. Pass the command input object directly
to `--json-input`, for example `{"title":"Example","priority":"high"}`; the CLI wraps the HTTP
request for you and binds Shadow OAuth identity, server membership, App grants, and command policy.
Use progressive disclosure: start with `shadowob app skills` or `shadowob app discover`, then call
`shadowob app call   --server  --help` only when you need that command's
full schema, file-upload support, or examples. For realtime app updates, subscribe with
`shadowob app events  --server  --json` instead of polling.
When a channel message mentions a server App, use the mentioned app key/server id directly and pass
the current channel id with `--channel-id` when available. If a server App command requires
approval, do not send a chat form or call the approval endpoint yourself as a Buddy. Wait for a
person to confirm the Shadow approval popup, then retry the original command.

```bash
# Legacy workspace apps
shadowob apps list  --json

# Get app
shadowob apps get  --json

# Create/Update/Delete
shadowob apps create  --name  --type  [--source-url ] [--description ] [--settings ] --json
shadowob apps update  [--name ] [--description ] [--source-url ] [--settings ] --json
shadowob apps delete 

# Publish from workspace
shadowob apps publish  --folder-id  [--name ] [--description ] --json

# Download source
shadowob apps download  [--output ]
```

## Notifications

```bash
# List notifications
shadowob notifications list [--unread-only] [--limit ] --json

# Get/Read/Delete
shadowob notifications get  --json
shadowob notifications mark-read 
shadowob notifications mark-all-read
shadowob notifications delete 

# Preferences
shadowob notifications preferences get --json
shadowob notifications preferences update [--email-enabled ] [--push-enabled ] [--mentions-only ] --json
```

## Friends

```bash
# List friends
shadowob friends list --json

# Friend requests
shadowob friends requests [--incoming] [--outgoing] --json
shadowob friends add  [--message ] --json
shadowob friends accept  --json
shadowob friends reject  --json

# Remove friend
shadowob friends remove  --json
```

## Invites

```bash
# List your invite codes
shadowob invites list --json

# Create invite code
shadowob invites create [--max-uses ] [--expires-in ] --json

# Deactivate/Delete invite
shadowob invites deactivate 
shadowob invites delete 
```

## OAuth

```bash
# List OAuth apps
shadowob oauth list --json

# Create OAuth app
shadowob oauth create --name  [--description ] [--redirect-uri ] [--homepage ] --json

# Update/Delete OAuth app
shadowob oauth update  [--name ] [--description ] [--redirect-uri ] [--homepage ] --json
shadowob oauth delete 

# Reset client secret
shadowob oauth reset-secret  --json

# List authorized apps (user consents)
shadowob oauth consents --json

# Revoke consent for an app
shadowob oauth revoke 

# External app commerce entitlement checks use OAuth access tokens, not user JWTs
shadowob oauth commerce check --access-token  --resource-id :premium --json
shadowob oauth commerce redeem --access-token  --resource-id :premium --idempotency-key  --json
```

## Marketplace

```bash
# Listings
shadowob marketplace listings list [--agent-id ] [--min-price ] [--max-price ] --json
shadowob marketplace listings get  --json
shadowob marketplace listings create --agent-id  --price  [--description ] --json
shadowob marketplace listings update  [--price ] [--description ] [--active ] --json
shadowob marketplace listings delete 

# Contracts
shadowob marketplace contracts list [--as-renter] [--as-owner] [--active-only] --json
shadowob marketplace contracts get  --json
shadowob marketplace contracts create --listing-id  --hours  [--note ] --json
shadowob marketplace contracts cancel 
shadowob marketplace contracts extend  --hours  --json
```

## Media

```bash
# Upload a file
shadowob media upload --file  [--server ] [--channel-id ] --json

# Download a file
shadowob media download  [--output ]
```

## Search

```bash
# Search messages
shadowob search messages --query  [--server ] [--channel-id ] [--author-id ] [--after ] [--before ] [--has-attachments] [--limit ] --json
```

## Listen (Real-time Events)

```bash
# Stream mode: listen until timeout or count
shadowob listen channel  --mode stream [--timeout 60] [--count 10] --json

# Poll mode: fetch recent messages
shadowob listen channel  --mode poll [--last 50] --json

# Filter events
shadowob listen channel  --event-type message:new,reaction:add --json

# DM events
shadowob listen dm  [--timeout 60] --json
```

## Output Format

- Default: human-readable list format
- `--json`: JSON output for programmatic use

## Error Handling

Commands exit with code 1 on error. Use `--json` to get structured errors:

```json
{ "error": "message" }
```