The Octospark CLI is an agent-friendly command line client over the Octospark API gateway. It uses the same public surface as the SDKs and MCP tools, so product operations stay behind the API instead of calling social, storage, or billing providers directly.

​
Install

npm install -g @octospark/cli
octospark login
You can also run it without installing: 
npx @octospark/cli login
npx @octospark/cli posts list --team-id <teamId>
npx @octospark/cli posts create --team-id <teamId> --text "Shipping update" --dry-run
The package installs a single octospark binary. It defaults to the production API.

​
Authentication

Create an API key in Octospark from Organization settings - API Keys. Use it as a bearer token: 
OCTOSPARK_TOKEN=<token> octospark whoami
For interactive terminal use, you can also sign in with Device Authorization Flow: 
octospark login
octospark whoami
octospark logout
octospark login starts Device Authorization Flow and stores a local auth profile at ~/.octospark/auth.json with owner-only permissions. Later commands reuse that profile automatically.

​
Environments

The CLI defaults to the production API. Use OCTOSPARK_API_URL or --api-url to target another environment. 
OCTOSPARK_API_URL=https://api.octospark.ai octospark login

​
Common Commands

octospark orgs list --fields response.data.id,response.data.name
octospark teams list --organization-id <organizationId> --fields response.data.id,response.data.name

octospark posts list --team-id <teamId> --fields response.total,response.data
octospark posts create --team-id <teamId> --text "Shipping update" --dry-run
octospark posts schedule <postId> --team-id <teamId> --account-id <socialAccountId> --at 2026-05-08T20:00:00.000Z --dry-run
octospark posts publish <postId> --team-id <teamId> --account-id <socialAccountId> --dry-run

octospark assets list --team-id <teamId> --fields response.total,response.data
octospark assets search "launch image" --team-id <teamId>
octospark assets upload ./image.png --team-id <teamId> --dry-run

octospark accounts list --team-id <teamId>
octospark analytics summary --team-id <teamId> --dry-run
octospark billing balance --organization-id <organizationId>

​
Agent-Friendly Output

Use --json for a stable command envelope: 
octospark posts list --team-id <teamId> --json
Use --fields to keep responses compact: 
octospark surfaces list --fields key,cliCommand,mcpTool,apiStatus
Use --request @payload.json for larger requests: 
octospark social create-post --dry-run --request @payload.json

​
Safety

Mutating commands and paid-read operations should be previewed with --dry-run first. Run the final command with --yes only after reviewing the plan or cost estimate. 
octospark billing topup --organization-id <organizationId> --amount-dollars 10 --success-url https://octospark.ai/billing/success --cancel-url https://octospark.ai/billing --dry-run
octospark billing topup --organization-id <organizationId> --amount-dollars 10 --success-url https://octospark.ai/billing/success --cancel-url https://octospark.ai/billing --yes

​
Surface Discovery

The CLI can inspect the generated API-backed surface used by CLI and MCP: 
octospark surfaces list --fields key,cliCommand,mcpTool,apiMethod,apiPath
octospark surfaces describe social.create_post
octospark schema social.create_post

​
Agent Skills

Install bundled Codex or Claude Code skills: 
octospark skills list
octospark skills install --target codex --dry-run
octospark skills install --target claude