CLI

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-staging.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://staging.octospark.ai/billing/success --cancel-url https://staging.octospark.ai/billing --dry-run
octospark billing topup --organization-id <organizationId> --amount-dollars 10 --success-url https://staging.octospark.ai/billing/success --cancel-url https://staging.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

Start

API reference

Install

Authentication

Environments

Common Commands

Agent-Friendly Output

Safety

Surface Discovery

Agent Skills

​Install

​Authentication

​Environments

​Common Commands

​Agent-Friendly Output

​Safety

​Surface Discovery

​Agent Skills

Install

Authentication

Environments

Common Commands

Agent-Friendly Output

Safety

Surface Discovery

Agent Skills