Install & authenticate

The CLI ships as @theplato/tiro-cli on npm for macOS, Linux, and Windows. For security, use Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x).

1. Install

Recommended Node.js for security is 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x). This recommendation is separate from the current npm package installation requirements.Before installing, check your Node.js version and the Node.js requirements of the CLI release on npm.

node --version
npm view @theplato/tiro-cli engines

If your Node.js version is outside the recommended security ranges or does not meet the reported installation requirements, update Node.js to meet both before installing the CLI.

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.6.4 (or later) — OAuth login requires 0.6.4+

tiro auth login

This starts an OAuth Authorization Code + PKCE sign-in in your default browser. The CLI opens a one-shot local server on http://127.0.0.1:<random-port>/callback to receive the redirect. After you sign in, the JWT is kept in your operating system’s 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__...***

Only the start of the token is shown. The full bearer token never leaves the keychain.

The CLI acts as the signed-in user. Its reach is therefore the same as the notes you see in the app, including notes in your own private folders. A system API key is different: it reads only notes in folders shared with all members (What notes a system API key reads). If your automation has to work with notes in private folders, use the CLI or an account API key.

3. Sign out

tiro auth logout

Clears the keychain entry. Your next tiro auth login starts a new OAuth session with Tiro’s fixed public 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`)
`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.

Home

Getting Started

API

Voice File

Webhooks

MCP

CLI

Developer Resources

Install & authenticate

1. Install

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

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