Spooling
CLI Reference
Back to spooling.ai

spooling cloud

Spooling Cloud auth, status, watch, and delete subcommands.

spooling cloud [login|logout|status|watch|delete] ...

spooling cloud is the group of subcommands that talk to api.spooling.ai. Authentication is a single API key per CLI install, stored at ~/.config/spooling/cloud.json. Switch workspaces by signing in again and choosing a different one.

login

Sign in to Spooling Cloud. With no flags it opens your browser, you approve the login and choose the workspace, and the CLI stores a key for future spooling push and spooling cloud … calls. spooling login is a shortcut for the same thing.

spooling login [--no-browser]
spooling cloud login --key sk_<token> [--api-url URL]    # paste a key you minted in the app instead
FlagDescription
--keyOptional. Skip the browser and use a key you minted in Settings in the app.
--no-browserPrint the approval link instead of opening it (for remote machines).
--api-urlOverride the API base. Defaults to https://api.spooling.ai.

The key is bound to whichever workspace was active when you minted it. To re-point the CLI at a different workspace, just run login again with a key from that workspace.

logout

Forget the stored key.

spooling cloud logout

status

Show the current login + a tiny stats summary from the cloud.

spooling cloud status

Output:

API: https://api.spooling.ai
  sessions: 108
  messages: 32593
  providers: 5
  cost: $51.26

watch

Continuously push new local sessions. Polls the local DB every --interval seconds and ships anything since the last push watermark.

spooling cloud watch [--interval 60] [--limit 1000]
                  [--batch 20] [--lookback 10]
FlagDescription
--intervalSeconds between push cycles. Default: 60.
--limitMax sessions per cycle. Default: 1000.
--batchSessions per HTTP request. Default: 20.
--lookbackMinutes to overlap on each cycle to catch updated sessions. Default: 10.

watch does not run spooling sync. Pair it with spooling watch (provider files → local DB) for a continuous local-to-cloud pipeline.

delete

Free session IDs in the workspace this key authenticates to. Use this when sessions ended up in the wrong workspace and you want to re-push them to the right one without leaving a copy behind.

spooling cloud delete [--project NAME] [--cwd SUBSTR] [--session-id ID]
                   [--all] [--yes] [--dry-run]
FlagDescription
--project NAMEDelete sessions whose project name matches exactly.
--cwd SUBSTRDelete sessions whose cwd contains this substring.
--session-id IDDelete a single session by its id. Use when project/cwd cannot isolate it (e.g. seed data with project=null).
--allDelete every session in the current workspace. Requires --yes.
--yesSkip the confirmation prompt. Required with --all.
--dry-runPrint which sessions would be deleted and exit.

At least one of --project, --cwd, --session-id, or --all is required. Tenant scope is enforced server-side from the auth context, so a key cannot delete sessions in any workspace it doesn't own.

Common pattern

spooling cloud login --key sk_<wrong-workspace-key>
spooling cloud delete --cwd toebox --dry-run    # verify
spooling cloud delete --cwd toebox

spooling cloud login --key sk_<right-workspace-key>
spooling push --cwd toebox

If you'd rather share the sessions across workspaces (keep them in both), use spooling push --copy instead of delete + re-push.

On this page