@cubster/cli

The agent-first command-line tool for the Cubster Assets API — 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.

Install

npm install -g @cubster/cli

(Not yet published — see the repo root for local usage during development.)

Quick start

cubster login              # paste a csk_... key created at app.cubster.dev
cubster whoami              # confirm who/what workspace you're bound to
cubster upload ./hero.png --tags marketing,hero
cubster assets ls --type image
cubster assets rm <id>

Global options

Every command accepts:

| Flag | Description | | --- | --- | | --json | Print machine-readable JSON instead of human-readable text | | --base <url> | API base URL (default: https://app.cubster.dev) | | --key <key> | Use this API key for just this invocation | | -h, --help | Show help for the command |

Config & auth

Credentials resolve with this precedence, highest first:

1. --key / --base flags
2. CUBSTER_API_KEY / CUBSTER_BASE_URL environment variables
3. The config file: ~/.config/cubster/config.json (or $XDG_CONFIG_HOME/cubster/config.json)
4. The SDK default base URL (https://app.cubster.dev) — there's no default key

cubster login writes the config file with owner-only permissions (0600). The full key is never printed, logged, or included in --json output — only its non-secret csk_xxxxxxxx… prefix is ever shown.

Key management (create/list/revoke) is intentionally not available here — a pasted key can't mint other keys. Manage keys at app.cubster.dev.

Commands

cubster login

Prompt for a csk_... key (or pass --key non-interactively, for CI/agents), verify it against /me, and store it. Prints where it was stored and the key's prefix — never the key itself.

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

cubster whoami

Calls client.me.get() and prints the profile email, the credential's bound workspace (name/slug), and the base URL in use.

cubster whoami
cubster whoami --json

cubster upload <path>

Upload a local file (file path only — no stdin in this version).

| Flag | Description | | --- | --- | | --name <name> | Display name (default: the filename) | | --tags a,b | Comma-separated tags | | --workspace <id\|slug> | Target a specific owned workspace |

cubster upload ./hero.png --name "Marketing hero" --tags hero,landing

cubster assets ls

List assets. A table by default, a JSON array with --json.

| Flag | Description | | --- | --- | | --type image\|file | Filter by kind | | --search <text> | Match display name / original filename | | --tags a,b | Match assets containing ALL of these tags | | --limit <n> | Max results (API caps at 100) | | --workspace <id\|slug> | Target a specific owned workspace |

cubster assets rm <id>

Delete an asset. 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

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Runtime error (network/API failure, missing file, no API key configured) | | 2 | Usage error (bad flags, missing required argument, unknown command) |

Development

npm run build -w @cubster/cli
npm test -w @cubster/cli

See docs/autopilot/2026-07-25-cli-testplan.md at the repo root for the manual/live test plan (requires a dashboard-created key).

License

MIT