ceum

ceum is the command-line client for Ceum. It uses a Ceum MCP token to run workspace operations from the same API surface used by Ceum's MCP endpoint.

Use it to work with tasks, clients, projects, invoices, time entries, transactions, and subscriptions. Output can be formatted as text, JSON, CSV, or NDJSON for scripts and reports.

$ ceum tasks list --status open -o json | jq '.[].title'
$ ceum tasks create --title "Ship v1" --status todo
$ CEUM_TOKEN=ceum_… ceum invoices list        # headless / CI

Install

npm install -g @ceum/cli
# or run without installing
npx @ceum/cli --help

Installs the ceum command. Requires Node.js 22+.

Authenticate

ceum authenticates with an MCP token (Pro plan). Mint one in the Ceum web app under Settings → MCP, then:

$ ceum auth login
Paste your Ceum MCP token (starts with ceum_): ****************
Signed in. 42 tools available under this token.

The token is stored in ~/.config/ceum/config.json (mode 0600). Precedence, highest first:

1. --token <ceum_…>
2. CEUM_TOKEN environment variable (ideal for CI — nothing written to disk)
3. the active profile in the config file

Profiles

Keep separate tokens/endpoints (e.g. work vs. a client's workspace) as named profiles:

$ ceum auth add work           # prompt + validate a token, make it active
$ ceum auth list               # * marks the active profile, tokens masked
$ ceum auth use work           # switch the active profile
$ ceum --profile work tasks list
$ ceum auth remove work
$ ceum auth status             # active profile + masked token + endpoint
$ ceum auth logout             # clear the active profile's token

Commands

The command surface is derived live from the tools your token is granted, so ceum --help and completion always reflect exactly what you can do. The grammar is resource-first:

| Tool | Command | Literal alias (also works) | | ----------------------- | -------------------------- | ---------------------------- | | create_task | ceum tasks create | ceum create task | | list_time_entries | ceum time-entries list | ceum list time entries | | bulk_delete_tasks | ceum tasks bulk-delete | ceum bulk delete tasks | | link_task_to_projects | ceum tasks link-projects | ceum link task to projects |

Run ceum --help to list the commands available to your token.

$ ceum --help                     # resources + actions your token can run
$ ceum tasks create --help        # flags for one command (from its schema)
$ ceum tasks list -o json | jq    # machine output
$ ceum                            # interactive UI (on a TTY)
$ ceum -x                         # force scriptable mode (no UI), even on a TTY

For inputs that don't map cleanly to flags, pass a raw JSON object:

$ ceum tasks update --id T-12 --input '{"customFields":{"due":"2026-08-01"}}'
$ ceum invoices create --input-file ./invoice.json

Output formats

Choose an output with -o (default text). text tabulates lists and pretty-prints single records; machine formats are always byte-clean (no color/box-drawing).

$ ceum tasks list                        # aligned table (boxed on a TTY)
$ ceum tasks list -o json | jq .         # --json is an alias for -o json
$ ceum tasks list -o csv > tasks.csv     # RFC-4180 CSV
$ ceum tasks list -o ndjson | while read l; do …; done
$ ceum tasks list --columns id,title,status
$ ceum tasks create --title X -q         # --quiet: print only the new id

Bulk import

Feed rows from a file (--file) or stdin (--stdin) to a bulk-create/update/delete command. Input is auto-detected: JSON array, single JSON object, NDJSON/JSONL, or CSV. Rows are chunked to the server's 50-per-request cap and applied in order.

$ ceum clients bulk-create --file clients.ndjson
$ jq -c '.[]' data.json | ceum transactions bulk-create --stdin
$ ceum tasks bulk-delete --file ids.csv        # ids column → delete
$ ceum tasks bulk-update --file patches.ndjson # {"id":"T-1","title":"…"} → patch

By default a failing chunk is reported and the rest continue (exit 5 if any row failed); --fail-fast stops at the first failure.

Auto-pagination

--all walks every page of a list command past the per-request cap and merges the results:

$ ceum transactions list --all -o csv > all-transactions.csv

Interactive UI

Run ceum with no command on a TTY to open the interactive UI: a guided, arrow-key session that reuses one connection and drives the same operations as the flag-based commands.

• Pick a resource, then an action (arrow keys + enter).
• For a list, optionally start from a saved preset, choose filters, then browse the results and select a row to see its detail and act on it (view/edit/flag/delete).
• For create/edit, fill a form generated from the command's schema; known fields (status, type, project, client, tag) offer a picker of real options instead of raw slugs.
• All prompts go to stderr; a "view" prints the record to stdout, so you can still pipe.

Nothing is interactive-only — every action maps to a ceum <resource> <action> … command you can script. Press Ctrl-C to leave a menu or quit. Piped/redirected input (or -x/--script) always runs non-interactively.

Line REPL

The previous line-oriented REPL is still available as ceum repl — one connection, tab-completion over resources/actions/flags, and history at $XDG_STATE_HOME/ceum/history:

ceum> tasks list --status open
ceum> .refresh          # re-fetch the tool catalog
ceum> exit

Presets & defaults

Save a set of list filters once and reuse it — interactively (the list view offers your presets) or from scripts:

$ ceum presets save tasks overdue --overdue --status in-progress   # validate + save
$ ceum presets list                                                 # all saved presets
$ ceum tasks list --preset overdue -o json | jq                     # apply it (explicit flags win)
$ ceum presets rm tasks overdue

Global defaults live alongside your profiles in the config file:

$ ceum defaults set output json          # default -o for every command
$ ceum defaults set page-size 25          # default list page size
$ ceum defaults set preset tasks overdue  # auto-offer this preset when listing tasks in the UI
$ ceum defaults show
$ ceum defaults clear output

Piping & exit codes

Only command output goes to stdout; prompts, progress, and errors go to stderr, so pipelines stay clean. Exit codes encode the failure class: 0 ok, 2 usage, 3 auth, 4 forbidden, 5 tool error, 6 network, 7 config.

Shell completion

$ ceum completion zsh  >> ~/.zshrc     # or: bash >> ~/.bashrc

Configuration

| Variable | Purpose | | ----------------- | --------------------------------------- | | CEUM_TOKEN | MCP token (overrides the config file) | | CEUM_API_URL | MCP endpoint (defaults to api.ceum.app) | | XDG_CONFIG_HOME | Base dir for ceum/config.json | | XDG_STATE_HOME | Base dir for the REPL history file | | NO_COLOR | Disable colored output |

License

MIT.