Developers

Use the Troopy CLI

View as MarkdownOpen the page as plain text Open in ChatGPTAsk questions about this page Open in ClaudeAsk questions about this page

Install the troopy command, sign in with a key, and run any operation of the API from your terminal.

The troopy command runs any operation of the Troopy API from your terminal. Each command is one call to the API, so the CLI can do what the API does. This page tells how to install it, sign in with a key, and use it in scripts.

Before you begin

Node.js 20 or newer.
An API key. Open Settings > API keys, pick the Scopes, and select Create key. Viewers, approvers and guests make no keys. See Manage your account.

Run it with npx, or install it

npx -y troopy runs the latest version with no install. To keep the command, install it:
bash
```
npm install -g troopy
```
Sign in with your key
bash
```
npx -y troopy login
```
Paste the key when the CLI asks. The CLI checks the key with Troopy, then says who you are and in which workspace.
Check who you are
bash
```
npx -y troopy whoami
```

The key goes in ~/.troopy/config.json, which only you can read. troopy logout forgets it.

Run a command

A command is the name of a part of Troopy and a verb, such as tasks list. Each field of the operation is a flag.

bash

1troopy tasks list --status needs_you2troopy tasks create --title "Write the launch email" --assignee writer3troopy tasks comment --key VIR-12 --text "Add the price too"4troopy chat start --agent chief --message "What did the troop do this week?"5troopy guides search --q "public dashboard"

troopy --help lists every command.
troopy <command> --help shows its flags, the flags that it needs, and its path in the API.
A flag takes the field name in lowercase, with dashes: updatedSince is --updated-since.

The API reference names the CLI command of each operation.

Values of flags

Value	How to give it
A list	Words with commas, `--labels bug,urgent`, or JSON.
An object	JSON: `--values '{"key":"..."}'`.
A file	`@` and its path: `--content @./brief.pdf`.
A value from the input	`@-` reads it from standard input. Thus a secret stays out of the history.

For example, put an API key in the vault with no key in the command:

bash

printf %s "$STRIPE_KEY" | troopy vault add --kind api_key --name Stripe --values @-

Use it in scripts

Option or variable	What it does
`--json`	Prints the answer as JSON. The CLI also prints JSON when you pipe it.
`--api-key <key>`	Uses this key for one command.
`TROOPY_API_KEY`	The key, from the environment. A CI job uses it.
`--api-url <url>`, `TROOPY_API_URL`	Another address of Troopy. The default is `https://troopy.ai`.
`TROOPY_CONFIG_DIR`	Another folder for the saved key.
`--idempotency-key <key>`	Your own key for a change. A second call with the same key runs nothing.

The CLI looks for the key in this order: --api-key, then TROOPY_API_KEY, then the key of troopy login. Each command that changes data sends a new idempotency key by itself.

Exit codes

Code	What it means
0	The command worked.
1	Another error. The message says what went wrong.
2	The key is wrong, or it lacks a scope.
4	Too many calls. Wait, then try again.

Run a local MCP server

troopy mcp runs Troopy as an MCP server on your computer, over stdio. An AI assistant then uses Troopy with your key:

bash

claude mcp add troopy --env TROOPY_API_KEY=tr_live_... -- npx -y troopy mcp

Prefer the remote server, which needs no install. See Connect an AI assistant with MCP.

Use the Troopy CLI

Before you begin

Install and sign in

Run a command

Values of flags

Use it in scripts

Exit codes

Run a local MCP server

Related