CLI (command line)

The tracker CLI (the @aquarela/tracker package on npm) brings tracker to the terminal. It's the simplest path for agents that run commands, like Claude Code and Codex: they already know how to use a CLI, read the help on their own and don't load the MCP tools into their context. Under the hood it's the REST API, with the same rules and permissions as the app, on behalf of whoever logged in.

Install and log in

npm install -g @aquarela/tracker
tracker login

Requires Node.js 20 or newer (without installing: npx @aquarela/tracker). tracker login opens the browser: the person authorizes the CLI on a screen like the MCP one, choosing the companies and whether it can write. The login is stored in ~/.config/tracker, readable only by that person, and renews automatically; tracker logout logs out and disconnects. Without a browser (server, container, CI), use a personal token: TRACKER_TOKEN in the environment, or tracker login --with-token with the token on standard input. tracker whoami shows who is logged in, the companies and the access. People find these commands, ready to copy, at https://tracker.aquarela.app/account/cli (Your account → Apps and API → CLI).

Commands

• tracker issues list: the GET /issues search, with the same filters (-p project, --open, --mine, -s status, -q text, --query advanced query, --filter saved filter, --limit, --offset).
• tracker issues view <code>: the issue, with --comments for the comments and --fields for only some parts.
• tracker issues create: creates one (-p, -t, -d or -D with a file, --type, --severity, --priority, -a, -l, --field, --external-id, --similar).
• tracker issues update <code>: edits only what you send (--assignee, --add-label, --remove-label, --sprint, --release, --fix-notes, --edit-version and more).
• tracker issues status <code> <status>: changes the status by the project workflow key (--reason when closing).
• tracker issues comment <code>: comments (-b text, -B a file or standard input, --reply-to, --attach).
• tracker issues attach <code> <files>: attaches; above 15 MB, through the direct upload of POST /uploads.
• tracker projects list and tracker projects view <prefix>: the projects, with each one's statuses, types and fields.
• tracker similar "<text>" (or --issue <code>): "Has this happened before?", through GET /search.
• tracker docs list, tracker docs search "<question>" and tracker docs view <slug>: the knowledge base.
• tracker org list and tracker org use <slug>: the login's companies and the default one.
• tracker api <route>: any API route, with the CLI's login, like gh api: -X the method, -f and -F (typed) build the JSON body, --input sends a ready body.
• tracker llms: this manual, no login needed.

tracker <command> --help shows each command's options and examples.

For agents and scripts

• --json on any command prints the API response as it came, with the fields documented here. Errors go to standard error, as JSON with --json (error, message, status).
• Exit codes: 0 success, 1 API or network error, 2 wrong usage, 4 not logged in or login expired.
• --org <slug> (or TRACKER_ORG) picks the company for the call, through the X-Tracker-Organization header, when the login covers more than one.
• At the rate limit (429), the CLI waits for Retry-After and tries again.
• Environment: TRACKER_TOKEN, TRACKER_ORG, TRACKER_HOST (default https://tracker.aquarela.app) and TRACKER_LANG (pt, en or es; without it, the account's language).

Example instruction for a repository's AGENTS.md or CLAUDE.md:

This repository's tasks live in tracker, project MOB. Use the `tracker` CLI with --json:
`tracker issues list -p MOB --open --json`, `tracker issues view` and `tracker issues comment`.
Before creating a task, run `tracker similar`.