> ## 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 the Tiro CLI in your agent

> One prompt — your agent installs the Tiro CLI, runs OAuth in your browser, and confirms the session is live.

Paste the block below into Claude Code, Cursor's terminal agent, or any coding agent with shell access. The agent installs `@theplato/tiro-cli` from npm, runs OAuth in your browser, and verifies the session.

**Requirements**  ·  Node.js 20+  ·  macOS, Linux, or Windows  ·  a shell the agent can run commands in

## Copy this prompt

```text The Tiro CLI install prompt theme={"system"}
Install the Tiro CLI in this environment and sign me in.

  Package    :  @theplato/tiro-cli  (Node.js 20+)
  Platforms  :  macOS, Linux, Windows
  Auth       :  OAuth (Authorization Code + PKCE) — opens a browser
                and stores the token in the OS keychain.

Steps:
  1. Install globally with whichever package manager is already in
     use here. For npm, that is:
       npm install -g @theplato/tiro-cli
     (Use pnpm / yarn / bun equivalents if those are the active
     package manager — do not switch tooling.)
  2. Verify the install:
       tiro --version            # expect 0.3.1 or later
  3. Sign me in:
       tiro auth login           # opens a browser for OAuth
  4. Confirm the session:
       tiro auth status          # shows user + token prefix only

If this is a headless / CI / sandboxed environment without a browser,
do not run `tiro auth login`. Instead, ask me for a TIRO_TOKEN value
and export it for subsequent commands:

  export TIRO_TOKEN="<paste-token-here>"

When everything is connected, run:

  tiro notes list --limit 3 --json

and show me the output to prove the CLI is working. If any step
fails, show the exact command, the exit code, and the error — do
not retry silently.
```

<Tip>
  The prompt tells the agent to **respect the package manager already in use** in your workspace. You won't end up with both `npm` and `pnpm` lockfiles after the install.
</Tip>

## What your agent will do

1. Detect your package manager (npm / pnpm / yarn / bun) and install `@theplato/tiro-cli` globally.
2. Verify the binary is on `PATH` by running `tiro --version`.
3. Run `tiro auth login` — your browser opens for OAuth. The bearer token is stored in the OS-native keychain (Keychain / Secret Service / Credential Manager).
4. Call `tiro auth status` and `tiro notes list --limit 3 --json` to prove the connection.

In a headless environment, the agent pauses on step 3 and asks you for a `TIRO_TOKEN` instead — see [Headless, CI, and agent environments](/en/developers/cli/setup#headless-ci-and-agent-environments) for how to mint one.

## Privacy & token handling

* OAuth tokens are stored in the OS-native credential store. The full bearer never appears on stdout — only a prefix like `tk__...***`.
* `TIRO_TOKEN`, if set, overrides the keychain — useful for CI secrets, dangerous if it leaks into shell history.
* Rotate by running `tiro auth logout && tiro auth login` on a trusted machine, then update the secret store.

***

Prefer to install it yourself?  → [Manual install & auth](/en/developers/cli/setup)   ·   [Quickstart scenarios](/en/developers/cli/quickstart)   ·   [Agent guide](/en/developers/cli/agent-guide)