> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# Install & authenticate

> Install the CLI from npm, authenticate via browser OAuth, and set up headless / CI environments.

The CLI ships as `@theplato/tiro-cli` on npm and runs on Node.js 20+. macOS, Linux, and Windows.

## 1. Install

<CodeGroup>
  ```bash npm theme={"system"}
  npm install -g @theplato/tiro-cli
  ```

  ```bash pnpm theme={"system"}
  pnpm add -g @theplato/tiro-cli
  ```

  ```bash yarn theme={"system"}
  yarn global add @theplato/tiro-cli
  ```

  ```bash bun theme={"system"}
  bun add -g @theplato/tiro-cli
  ```
</CodeGroup>

Verify the install:

```bash theme={"system"}
tiro --version
# → 0.3.1 (or later)
```

<Note>
  **System requirements**: Node.js 20 or later. The shipped binary is ESM-only; Node 18 will error on import.
</Note>

## 2. Sign in

```bash theme={"system"}
tiro auth login
```

This opens your default browser to Tiro's OAuth Authorization Code + PKCE flow. The CLI runs a one-shot local HTTP server on `http://127.0.0.1:<random-port>/callback` to receive the redirect. After you sign in, the JWT is stored in your OS-native credential store:

* **macOS** — Keychain
* **Linux** — Secret Service (requires `gnome-keyring` or `kwallet`)
* **Windows** — Credential Manager

Confirm:

```bash theme={"system"}
tiro auth status
# ✓ Signed in
#   source:     keychain
#   hostname:   https://api.tiro.ooo
#   user:       <userId>
#   expires at: <ISO datetime>
#   token:      tk__...***
```

The token prefix is the only fragment ever shown — the full bearer token never leaves the keychain.

## 3. Sign out

```bash theme={"system"}
tiro auth logout
```

Clears the keychain entry and the cached Dynamic Client Registration ID. Your next `tiro auth login` registers a fresh DCR client.

## 4. Connect Tiro MCP to your agent (optional)

If you use Claude Code (or any MCP-compatible client), the CLI ships a one-line installer for the hosted Tiro MCP at `https://mcp.tiro.ooo/mcp`:

```bash theme={"system"}
tiro mcp install
# → claude mcp add --transport http tiro https://mcp.tiro.ooo/mcp
```

Pipe the output straight to your shell, or copy the command into your MCP client's config. Run `tiro mcp info --json` for a structured view (transport, URL, docs link). The CLI handles read-heavy flows (browse, save to disk); MCP handles interactive tool calls inside an agent loop. See [`AGENTS.md`](https://github.com/plato-corp/tiro-cli/blob/main/AGENTS.md) bundled with the package for the full agent contract.

## Headless, CI, and agent environments

Some environments can't open a browser (CI, SSH, sandboxed agents, Docker). For those, set `TIRO_TOKEN` directly. Any value here overrides the keychain.

```bash theme={"system"}
export TIRO_TOKEN="$(security find-generic-password -s 'io.tiro.cli' -a default -w 2>/dev/null \
  | jq -r '.accessToken')"
tiro notes list --json
```

In GitHub Actions:

```yaml theme={"system"}
- name: Run tiro
  env:
    TIRO_TOKEN: ${{ secrets.TIRO_TOKEN }}
  run: |
    tiro notes search "release notes" --since 1d --json > recent.jsonl
```

<Warning>
  Putting your full bearer token in a CI secret is equivalent to a 180-day Personal Access Token. Rotate by running `tiro auth logout && tiro auth login` on a trusted machine and copying the new token into the secret store.
</Warning>

## Configuration overrides

| Variable          | Purpose                                                    |
| ----------------- | ---------------------------------------------------------- |
| `TIRO_TOKEN`      | Bearer token — overrides keychain                          |
| `TIRO_HOSTNAME`   | API base URL (defaults to `https://api.tiro.ooo`)          |
| `TIRO_OUTPUT_DIR` | Default `--output-dir` for export commands (v0.3+)         |
| `NO_COLOR`        | Disable ANSI colors ([no-color.org](https://no-color.org)) |

Per-call overrides:

```bash theme={"system"}
tiro --hostname https://api.tiro-ooo.dev notes list      # dev environment
tiro notes get <guid> --json --no-color                  # script-friendly
```

## Update the CLI

<CodeGroup>
  ```bash npm theme={"system"}
  npm update -g @theplato/tiro-cli
  ```

  ```bash pnpm theme={"system"}
  pnpm update -g @theplato/tiro-cli
  ```

  ```bash yarn theme={"system"}
  yarn global upgrade @theplato/tiro-cli
  ```

  ```bash bun theme={"system"}
  bun update -g @theplato/tiro-cli
  ```
</CodeGroup>

→ Continue to [Quickstart](/en/developers/cli/quickstart) for hands-on examples.