CUBSTER Join the waitlist
DOCS / CLI

CLI

@cubster/cli is built on @cubster/assets. Log in with a pasted API key, upload files, and list/delete assets — from a terminal or from an agent, with clean --json output and predictable exit codes. It isn't published to npm yet — see the repo for local usage during development.

$ cubster login      # paste a csk_... key created at app.cubster.dev
$ cubster whoami
$ cubster upload ./hero.png --tags marketing,hero
$ cubster assets ls --type image
$ cubster assets rm <id>
$ cubster transcribe ./standup.m4a
$ cubster transcripts ls --status completed
$ cubster tags ls
Config & auth

Credentials resolve highest-precedence first: the --key/--base flags, then CUBSTER_API_KEY/CUBSTER_BASE_URL, then the config file (~/.config/cubster/config.json), then the SDK default base URL. cubster login writes that config file owner-only (0600). The full key is never printed, logged, or included in --json output — only its csk_xxxxxxxx… prefix is ever shown.

A command run with a key that lacks the route's service exits 1 with the API's own message printed as-is, e.g. This API key is not enabled for the 'transcription' service (enabled: assets). Create a key with that service at app.cubster.dev/account/keys.. With --json, the outcome also includes service and enabled fields.

cubster login

Prompts for a key (or takes --key non-interactively, for CI/agents), verifies it against /me, and stores it. Key management (create/list/revoke) isn't available here on purpose — manage keys at app.cubster.dev.

$ cubster login --key "$CUBSTER_API_KEY"  # non-interactive
cubster whoami

Prints the profile email, the credential's bound workspace, and the base URL in use. Signed in with an API key, it also prints a Services: line — the key's own service scope (a session credential has none to show).

$ cubster whoami
Email: you@example.com
Workspace: Acme (acme)
Base URL: https://app.cubster.dev
Services: assets, transcription
cubster upload <path>

A local file path (no stdin in this version). Flags: --name, --tags a,b, --workspace <id|slug>.

cubster assets ls / rm

ls — a table by default, a JSON array with --json; filter with --type, --search, --tags, --limit. rm <id> prompts for confirmation unless --yes is passed — and defaults to "no" (never deletes) when stdin isn't a TTY and --yes wasn't passed.

$ cubster assets rm abc123 --yes
cubster transcribe <path>

Upload a local audio file and transcribe it (Deepgram Nova-3). Flags: --name, --language <tag>, --no-diarize, --tags a,b (comma-separated; lands on the transcript only, not the companion audio asset), --workspace <id|slug>. A file over the 4 MB cap is rejected locally, before anything is uploaded. A failed transcription still keeps the audio — the output includes a retry hint with the transcript id.

$ cubster transcribe ./standup.m4a --language en-US
Transcribed "standup.m4a" (t1) — completed, 1:33, 2 speaker(s)
[0] 0:00 Hi there.
[1] 1:33 Bye.
cubster transcripts ls / get / rm / retry

ls — a table by default, filter with --status/--tag <t>/--limit. get <id> prints the same header + speaker-turn rendering as transcribe's success output. rm <id> deletes the transcript and its audio asset (confirmation prompt unless --yes). retry <id> re-runs a pending/failed transcript, reusing the stored audio — a completed transcript responds 409.

$ cubster transcripts get <id>
$ cubster transcripts retry <id>
cubster tags ls / find / set

Workspace-wide across all six taggable types (assets, transcripts, diagrams, artifacts, charts, queries) — see Tags. ls lists the tag vocabulary with counts and a breakdown by type — run it before tagging something new, so you reuse a tag that's already in use rather than mint a near-duplicate. find <tag> lists every object carrying it. Both take --archived and a table-by-default / --json output. A key sees only the types its services cover.

set <type> <id-or-slug> replaces an object's tags entirely — type is one of asset, transcript, diagram, artifact, chart, or query. Exactly one of --tag <t> (repeatable) or --clear is required — passing both, or neither, exits 2. For a diagram, artifact, or chart this is a retag without publishing a new version; a query has no version at all, so tags set query routes to the same client.queries.update(slug, { tags }) that edits its title and definition.

$ cubster tags ls
$ cubster tags find auth
$ cubster tags set chart wN4jC8pXaTsQ --tag repo --tag weekly
$ cubster tags set query aB3dE6gH9jK2 --tag telemetry
$ cubster tags set asset <id> --clear
cubster events send / ls

Custom telemetry — see Events. send needs a key with the events service; ls (and every cubster query command below) needs queries instead — a send-only key can never read events back.

$ cubster events send --name skill.invoked --source claude-code --data tokens=120 --data model=opus
$ cubster events send --file ./events.json  # a JSON array, or { "events": [...] }
$ cubster events ls --name skill.invoked --data model=opus --limit 20

--data k=v may repeat: true/false becomes a boolean, a plain number becomes a number, and everything else (including a leading-zero value like 007) stays a string — a repeated key on send is a usage error, never a silent overwrite. The event's own resend key is --resend-key <k>, not --key (the global flag for which credential to use) — a repeat with the same key in the same workspace is ignored, not an error. A batch file is sent in requests of 500, sequentially; if one fails partway the error names how many were already accepted and which batch failed, so a resend (safe, because of the resend key) only needs to start from there.

cubster query create / update / get / ls / run / runs / archive / unarchive

Saved queries over events — see Queries. Every subcommand needs a key with the queries service. --file on create/update is always the bare query DEFINITION — never wrapped, and never validated locally; the server's path-annotated errors print as-is.

$ cubster query create --file ./skill-usage.json --title "Skill usage" --tag telemetry
$ cubster query run skill-usage-abc1  # every run stores a new query_runs row
$ cubster query run --file ./one-off.json  # stores nothing
$ cubster query runs skill-usage-abc1 --limit 5

A saved query has no versions — update edits it in place. run's table has one column per groupBy entry (a null group prints as (none)), then VALUE; below it, the window, a partial result note when the row cap was hit, and — for a saved run — its id. No cubster query delete — archive hides one reversibly, and unarchive restores it.

Exit codes
0 Success
1 Runtime error (network/API failure, missing file, no key configured)
2 Usage error (bad flags, missing argument, unknown command)