--- 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 ``` ## 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 ``` When building or modifying a Server App in an agent runtime, use the separate mounted `shadow-server-app` skill. This `shadowob` skill covers operating installed Apps through the CLI; the Server App skill covers development, publish, expose, persistence, and backup guidance. 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. ## Notifications ```bash # List notifications shadowob notifications list [--unread-only] [--limit ] --json # Read state shadowob notifications mark-read shadowob notifications mark-all-read # 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 ``` ## API Tokens ```bash shadowob api-tokens list --json shadowob api-tokens create --name "CI Token" [--scope read] [--expires-in-days 90] --json shadowob api-tokens delete ``` ## Discover ```bash shadowob discover feed [--type all|servers|channels|rentals] [--limit 20] --json shadowob discover search --query [--type all|servers|channels|rentals] [--limit 10] --json ``` ## Profile Comments ```bash shadowob profile-comments get [--limit 20] [--offset 0] --json shadowob profile-comments create --user-id --content "Great profile" [--parent-id ] --json shadowob profile-comments delete ``` ## Cloud `shadowob cloud` includes Shadow API-backed helpers for templates, deployments, and Cloud App exposure. Unknown root arguments are passed through to the standalone `shadowob-cloud` CLI. ```bash shadowob cloud templates create --file template.json --json shadowob cloud deployments list [--include-history] [--limit 20] [--offset 0] --json shadowob cloud deployments get --json shadowob cloud deployments create --file deployment.json --json shadowob cloud deployments destroy --json shadowob app expose --deployment --agent --id --port 4216 --kind server_app --app-key --json shadowob app publish --deployment --agent --server --port 4216 --manifest-file shadow-app.json --json shadowob app status --deployment --json shadowob app backup --deployment --json shadowob app restore --backup --deployment --json shadowob app unpublish --deployment [--uninstall] --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 ``` ## 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 ``` ## Voice ```bash shadowob voice join [--muted] [--deafened] [--watch] --json shadowob voice status --json shadowob voice mute [--off] --json shadowob voice leave --json shadowob voice browser install --json shadowob voice browser path --json shadowob voice bridge [--audio-out ./audio] [--screen-out ./screens] [--record-out ./recordings] --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 ``` ## 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" } ```