Kompass CLI

Kompass CLI is the first-party command-line interface for Kompass BMS. It is built primarily for LLM-driven skills and automations that need to read and write Kompass data without driving the Vue frontend or hand-rolling REST calls. Human operators are a secondary audience.

What it does

Subcommands map cleanly to API resources, so a skill or operator can predict the command from the URL structure. Output is a stable JSON envelope by default, with opt-in table  and pretty  renderers for human use.

1. Mint a Personal Access Token

The CLI authenticates with a Personal Access Token (PAT). Generate one from your Kompass profile UI:

1. Sign in to Kompass and open your profile.
2. Open the Personal Access Tokens section.
3. Create a token with a descriptive name (for example laptop-cli).
4. Copy the token immediately, the raw value is shown once and cannot be recovered later. Lost tokens must be revoked and regenerated.

Tokens grant the same access as your user account. Keep them out of shared scripts and source control.

2. Install the CLI

The CLI is a single static binary built from cli/  in the Kompass repository. You need Go 1.26 or newer:

cd cli
go build -o /usr/local/bin/kompass ./cmd/kompass
kompass --help

The same module is used by the Kompass MCP server, so future binary releases will cover both.

3. Authenticate

Either set the token in your environment:

export KOMPASS_TOKEN=<paste-token>
export KOMPASS_BASE_URL=https://your-instance.kompassbms.com   # optional

…or store it in ~/.config/kompass/config.jsonc  via the interactive flow:

kompass auth login
kompass auth whoami

Resolution order is environment > config file > defaults.

Command surface

Common flags: --output json|ndjson|table|pretty , --fields a,b,c , --filter key=value  (repeatable), --order field , --limit , --page , --all . Mutations require --confirm ; --dry-run  prints the request that would be sent.

Output contract

Every successful response is a JSON envelope:

{ "schema_version": "1", "data": { ... } }

Errors go to stderr in the same shape with a non-zero exit code:

{ "schema_version": "1", "error": { "code": 3, "message": "...", "status": 401 } }

The schema_version  field increases on breaking output changes. Additive changes (new fields under data ) do not bump it.

Exit codes

Common recipes

List open tasks for a project

kompass tasks list \
  --filter project=42 \
  --filter is_completed=false \
  --order due_date \
  --output ndjson \
  --fields id,title,due_date,assignee

Move a project phase (always dry-run first)

kompass projects set-phase 42 accepted --dry-run
kompass projects set-phase 42 accepted --confirm

Allowed phases: quote, accepted, surveyed, processed, checked, delivered, invoiced, paid, abandoned, suspended.

Complete a task

kompass tasks complete 7 --confirm

Create a diary entry

kompass diary create --confirm --data '{
  "project": 42,
  "date": "2026-05-04",
  "notes": "Survey completed."
}'

Pass --data -  to read JSON from stdin instead.

Need help?

If a command exits non-zero unexpectedly, re-run with --pretty  for readable error output, or check error.details  in the JSON envelope for the field-level validation message returned by the API.