# Use the Troopy CLI

> 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](/docs/account#api-keys).

## Install and sign in

1. **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
   ```

2. **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.

3. **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.

> [!WARNING]
> A key acts as you. Do not type it in a command, because the history of your shell keeps it. Use `troopy login` or
> the `TROOPY_API_KEY` variable.

## 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
troopy tasks list --status needs_you
troopy tasks create --title "Write the launch email" --assignee writer
troopy tasks comment --key VIR-12 --text "Add the price too"
troopy chat start --agent chief --message "What did the troop do this week?"
troopy 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](/docs/api#operations) 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](/docs/mcp).

## Related

- [API reference](/docs/api)
- [Connect an AI assistant with MCP](/docs/mcp)
- [Manage your account](/docs/account)
- [Limits and defaults](/docs/limits#workspace-and-api)