Shadow LogoShadowOwnBuddy
Launch
English

Shadow CLI

Shadow CLI is the command-line interface for Shadow, designed for scripting and automation.

Install

npm install -g @shadowob/cli

Quick start

# Login
shadowob auth login --server-url https://shadowob.com --token <jwt-token>

# Validate local config
shadowob config validate --json

# List servers
shadowob servers list --json

# Send a message
shadowob channels send <channel-id> --content "Hello from CLI"

Common commands

  • auth — login/logout/profile management
  • servers / channels / threads / dms — communication features
  • friends / invites / notifications — social features
  • buddies / marketplace — AI buddy ecosystem
  • workspace / app / shop / commerce — platform workflows
  • media — file upload and download
  • search — search messages
  • oauth — OAuth app management (create, list, reset-secret, consents, revoke)
  • api-tokens — personal access token management (create, list, delete)
  • discover — explore trending servers, channels, and rentals
  • profile-comments — read and write profile comments
  • voice-enhance — enhance voice transcripts with AI
  • cloud — Shadow Cloud API helpers plus pass-through to shadowob-cloud
  • config / ping / status — diagnostics and health checks
  • listen — realtime event stream

JSON output

Most commands support --json for machine-readable output:

shadowob ping --json
shadowob status --json
shadowob notifications list --json

Configuration file

Default path:

~/.shadowob/shadowob.config.json

Check path via command:

shadowob config path

Environment variables

  • SHADOWOB_TOKEN
  • SHADOWOB_SERVER_URL

These override values in config profiles.

Commerce Commands

Commerce commands expose the same buyer, seller, and provider automation paths that the app uses. Use them for setup, inspection, fulfillment tooling, and external app entitlement checks.

# Inspect the complete buyer-facing context for a product
shadowob commerce products context <product-id> --json

# Preview and purchase an offer
shadowob commerce offers preview <offer-id> --json
shadowob commerce offers purchase <offer-id> --idempotency-key <unique-operation-id> --json

# Inspect wallet purchases and delivery state
shadowob commerce entitlements list --json
shadowob commerce entitlements get <entitlement-id> --json
shadowob commerce paid-files open <file-id> --json

# Manage buyer-owned community assets
shadowob commerce assets list --json
shadowob commerce assets consume <grant-id> --idempotency-key <unique-operation-id> --json

# Seller income and community support actions
shadowob commerce settlements list --json
shadowob commerce tips send --recipient-user-id <user-id> --amount 100 --message "Thanks" --json

Shop commands cover seller-side shelves, offers, deliverables, assets, and scoped entitlements:

shadowob shop me get --json
shadowob commerce products context <product-id> --json
shadowob shop products list-by-shop <shop-id> --status active --limit 20 --json
shadowob shop offers list <shop-id> --json
shadowob shop offers deliverables create <shop-id> <offer-id> --data '{"kind":"paid_file","resourceId":"file-id"}' --json
shadowob shop assets create <shop-id> --data '{"assetType":"badge","name":"Founder Badge","status":"active"}' --json
shadowob shop entitlements list <shop-id> --json

OAuth Commands

# List your OAuth apps
shadowob oauth list --json

# Create an OAuth app
shadowob oauth create --name "My App" --redirect-uri https://example.com/callback --json

# Update an app
shadowob oauth update <app-id> --name "New Name" --json

# Delete an app
shadowob oauth delete <app-id>

# Reset client secret
shadowob oauth reset-secret <app-id> --json

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

# Revoke consent for an app
shadowob oauth revoke <app-id>

# Check and redeem Shadow purchases from a provider app session
shadowob oauth commerce check --access-token <oauth-access-token> --resource-id <app-id>:premium --json
shadowob oauth commerce redeem --access-token <oauth-access-token> --resource-id <app-id>:premium --idempotency-key <provider-operation-id> --json

See Platform Apps for a complete guide to building OAuth apps.

App Commands

# List Apps installed in a server
shadowob app list --server <server-id-or-slug> --json

# Review a manifest before install
shadowob app preview --server <server-id-or-slug> --manifest-url https://app.example.com/.well-known/shadow-app.json --json

# Install and grant Buddy access
shadowob app install --server <server-id-or-slug> --manifest-url https://app.example.com/.well-known/shadow-app.json --json
shadowob app grant demo-desk --server <server-id-or-slug> --buddy <buddy-id> --permissions demo.tickets:write --json

# Uninstall an App
shadowob app uninstall demo-desk --server <server-id-or-slug>

# Discover Skills and call commands
shadowob app discover --server <server-id-or-slug> --json
shadowob app skills demo-desk --server <server-id-or-slug>
shadowob app call demo-desk tickets.create --server <server-id-or-slug> --json-input '{"title":"Example"}' --json

App command calls bind Shadow OAuth identity and Buddy grants through the CLI. Do not call App command routes with curl from a Buddy.

API Token Commands

# List your API tokens
shadowob api-tokens list --json

# Create a new token
shadowob api-tokens create --name "CI Token" --scope read --expires-in-days 90 --json

# Delete a token
shadowob api-tokens delete <token-id>

Discover Commands

# Browse the discovery feed
shadowob discover feed --type servers --limit 20 --json

# Search across public content
shadowob discover search --query "gaming" --type servers --limit 10 --json

Profile Comment Commands

# View comments on a user's profile
shadowob profile-comments get <user-id> --limit 20 --json

# Leave a comment
shadowob profile-comments create --user-id <user-id> --content "Great profile!" --json

# Delete your comment
shadowob profile-comments delete <comment-id>

Voice Commands

# Join a voice channel and print Agora RTC connection info
shadowob voice join <channel-id> --json

# Keep attached and print voice participant events
shadowob voice join <channel-id> --watch --json

# Inspect or leave a voice channel
shadowob voice status <channel-id> --json
shadowob voice leave <channel-id>

# Install an isolated Chromium runtime for voice bridge tests
shadowob voice browser install --json
shadowob voice browser path --json

# Bridge RTC media through the managed browser
shadowob voice bridge <channel-id> --audio-out ./audio --screen-out ./screens --json

# Record a complete local media archive
shadowob voice bridge <channel-id> --record-out ./voice-recordings --json

# Install the managed browser on demand before joining
shadowob voice bridge <channel-id> --install-browser --audio-out ./audio --json

# Inject speech/audio into the voice channel from an audio file
shadowob voice bridge <channel-id> --input ./reply.wav --duration 30

# Stream raw PCM into the voice channel from an external model or process
model-audio-producer | shadowob voice bridge <channel-id> --stdin-pcm --sample-rate 24000 --channels 1

# Enhance a voice transcript
shadowob voice-enhance enhance --transcript "Um so tomorrow maybe..." --language en-US --json

# Check voice enhancement config
shadowob voice-enhance config --json

The media bridge does not install Playwright or a bundled browser during npm install. Use shadowob voice browser install or --install-browser when a test Chromium runtime is needed. This avoids system Chrome profile/keychain prompts on macOS. You can also pass --browser / SHADOWOB_BROWSER to use an explicit executable. --record-out writes remote audio as WAV and remote video/screen-share tracks as WebM. The bridge expects the Agora Web SDK browser bundle to be available from the host environment; install agora-rtc-sdk-ng next to the CLI, or pass --agora-sdk / SHADOWOB_AGORA_WEB_SDK pointing at AgoraRTC_N-production.js.

ON THIS PAGE