Skip to main content

CLI Reference

subscriberbot from @subscriberbot/cli. A thin shell over @burdenoff/cli-sdk: all command logic lives in shared SDK modules. This package builds the product CLIContext, mounts the modules the Subscriberbot surface needs, and wires the Commander program.

Install​

# From npmjs (public)
npm install -g @subscriberbot/cli
# or
bun add -g @subscriberbot/cli

Authentication​

All workspace operations require dual-token auth (platform token + workspace token). The workspace token is issued automatically when you set a workspace.

User Authentication (OAuth2 Device Code)​

Interactive browser-based login.

# Login — opens browser for approval
subscriberbot auth login

Production: The CLI auto-uses https://graphql.burdenoff.com/global as the OIDC issuer and burdenoff_cli_subscriberbot as the client id. Override per-config or via env vars (SUBSCRIBERBOT_OIDC_ISSUER, SUBSCRIBERBOT_WORKSPACE_ENDPOINT, SUBSCRIBERBOT_GLOBAL_ENDPOINT).

Common Auth Commands​

subscriberbot auth status                # Check current auth state
subscriberbot auth token                 # Print platform access token
subscriberbot auth token --workspace     # Print workspace token
subscriberbot auth refresh               # Force token refresh
subscriberbot auth logout                # Clear stored tokens

subscriberbot workspace list             # List available workspaces
subscriberbot workspace current          # Show current workspace
subscriberbot workspace set <id>         # Switch workspace (re-issues token)

Token storage: ~/.config/subscriberbot-cli/auth.json (mode 0600).

Commands​

The CLI mounts the following @burdenoff/cli-sdk module groups:

subscriberbot auth            Authentication (login, logout, status, token, refresh)
subscriberbot workspace       Workspace context (list, current, set)
subscriberbot organizations   Organization management
subscriberbot tours           Product tours
subscriberbot rbac            Role-based access control
subscriberbot subscriberbot       Subscriberbot subscription & relationship management
                          (providers, plans, relationships, assets, entitlements,
                          invoices, payments, channels, inbox, agents, workflows, health)
subscriberbot sandbox         Sandbox script execution
subscriberbot tags            Tags
subscriberbot files           Files
subscriberbot groups          Groups
subscriberbot conversations   Conversations
subscriberbot security        Security
subscriberbot integrations    Integrations
subscriberbot channels        Channels
subscriberbot scheduler       Scheduler
subscriberbot export          Data export
subscriberbot notifications   Notifications
subscriberbot support         Support
subscriberbot products        Products / feature flags
subscriberbot billing         Billing
subscriberbot store           Store
subscriberbot devportal       Developer portal
subscriberbot health          Health checks

Run subscriberbot <command> --help for subcommand details.

Quick Examples​

subscriberbot auth login
subscriberbot workspace set <id>
subscriberbot subscriberbot plans list
subscriberbot subscriberbot relationships list
subscriberbot subscriberbot providers list
subscriberbot tags create --key bug --label Bug
subscriberbot rbac check <user> read project
subscriberbot billing subscriptions list
subscriberbot devportal apps list --status PUBLISHED

Configuration​

CLI settings are stored in ~/.config/subscriberbot-cli/.

Default endpoints (production):

  • Workspace gateway: https://graphqlworkspaces.burdenoff.com/workspaces/graphql
  • Global gateway: https://graphql.burdenoff.com/global/graphql

Override per-config or via env vars: SUBSCRIBERBOT_WORKSPACE_ENDPOINT, SUBSCRIBERBOT_GLOBAL_ENDPOINT, SUBSCRIBERBOT_OIDC_ISSUER.

Output Formats​

All list/get commands support --format (-f): json, table, yaml.

Development​

Prerequisites​

  • Bun 1.3.14+
  • Node.js 24.11.0+
  • TypeScript 5.9+

Setup​

git clone https://github.com/algoshred/subscriberbot-cli.git
cd subscriberbot-cli
bun install

Commands​

bun run dev              # Run CLI in dev mode (tsx)
bun run dev -- --help    # Dev mode with args
bun run build            # Compile TypeScript (tsc + tsc-alias)
bun run type-check       # Type checking
bun run lint             # ESLint
bun run format           # Prettier
bun run sanity           # All checks (format + lint + type-check + build)
bun run start            # Run compiled CLI
Environment selection

The CLI targets production by default. To use local or alpha, set BURDENOFF_ENV:

# Alpha
BURDENOFF_ENV=alpha subscriberbot auth login

# Local
BURDENOFF_ENV=local subscriberbot auth login

See Environment Selection for the full endpoint matrix.