Install & authenticate

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

1. Install

npm install -g @theplato/tiro-cli

pnpm add -g @theplato/tiro-cli

yarn global add @theplato/tiro-cli

bun add -g @theplato/tiro-cli

Verify the install:

tiro --version
# → 0.3.1 (or later)

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

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:

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

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:

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

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:

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

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.

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)

Per-call overrides:

tiro --hostname https://api.tiro-ooo.dev notes list      # dev environment
tiro notes get <guid> --json --no-color                  # script-friendly

Update the CLI

npm update -g @theplato/tiro-cli

pnpm update -g @theplato/tiro-cli

yarn global upgrade @theplato/tiro-cli

bun update -g @theplato/tiro-cli

→ Continue to Quickstart for hands-on examples.

​1. Install

​2. Sign in

​3. Sign out

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

​Headless, CI, and agent environments

​Configuration overrides

​Update the CLI

1. Install

2. Sign in

3. Sign out

4. Connect Tiro MCP to your agent (optional)

Headless, CI, and agent environments

Configuration overrides

Update the CLI