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

# CLI Overview

> Agent-first command line for Tiro AI notes & transcripts.

The Tiro CLI is published on npm as [`@theplato/tiro-cli`](https://www.npmjs.com/package/@theplato/tiro-cli). It exposes the same Tiro APIs your MCP server exposes — but optimized for filesystem-heavy workflows, shell pipelines, and any environment where MCP isn't reachable (CI, cron, ad-hoc agent runs).

[![npm version](https://img.shields.io/npm/v/@theplato/tiro-cli)](https://www.npmjs.com/package/@theplato/tiro-cli)
[![Node.js](https://img.shields.io/node/v/@theplato/tiro-cli)](https://nodejs.org)

## Quick install

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

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

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

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

```bash theme={null}
tiro auth login                                 # browser opens; OAuth + PKCE
tiro notes search "Q3 Planning" --since 7d --json
```

## When to use which surface

|                        | **REST API**               | **MCP server**                    | **CLI**                          |
| ---------------------- | -------------------------- | --------------------------------- | -------------------------------- |
| Audience               | services, integrations     | MCP-aware AI clients              | shells, CI, ad-hoc agents        |
| Result lands in        | your code                  | agent **context window**          | **filesystem** or stdout pipe    |
| Per-session token cost | per request                | thousands (tool schema)           | dozens (per call)                |
| Best for               | service-to-service traffic | small reads, multi-turn reasoning | bulk export, file ops, scripting |
| Discovery              | OpenAPI                    | MCP `list_tools`                  | `tiro --help`                    |

The three surfaces share the same OAuth provider and JWT audience, so credentials issued for one work on the others. See [Authentication](/en/developers/fundamentals/authentication).

<Note>
  The CLI is **not a replacement for the MCP server**. It's the same data
  through a different surface, optimized for filesystem-heavy and shell-native
  workflows. For a Claude Desktop / Cursor / Code agent that primarily reads and
  reasons over notes inside a conversation, MCP stays the better fit. Use the
  CLI when you want results on disk or in a pipe.
</Note>

## What you get

* **Auth**: `tiro auth login | status | logout` — OAuth Authorization Code + PKCE with loopback redirect; tokens stored in OS Keychain.
* **Notes**: `tiro notes list | search | get | transcript` — covers the same surface as MCP's `list_notes` / `search_notes` / `get_note` / `get_note_transcript`.
* **Wiki**: `tiro wiki workspaces | search | page | mentions | graph` — read the auto-extracted knowledge graph; `--workspace <guid>` targets a specific workspace. Paid/opt-in, mirroring the MCP wiki tools.
* **MCP-shape JSON**: `tiro notes transcript --format json` mirrors the MCP `get_note_transcript` payload exactly. Reuse your MCP parser unchanged.
* **File output**: every retrieval command supports `--output <path>` so the actual content goes to disk and stdout shrinks to a metadata line. Critical for keeping agent context windows light.
* **Stable error envelope**: every error returns `{ ok: false, error: { code, message, suggestion?, errorType?, httpStatus?, requestId? } }` with documented exit codes.

## Architecture

```
                       Tiro Backend — /v1/external/* + /v1/mcp/*
                              │
       ┌──────────────────────┼──────────────────────┐
       ▼                      ▼                      ▼
  ┌──────────┐         ┌──────────────┐       ┌──────────────┐
  │ REST     │         │ MCP server   │       │ CLI          │
  │ clients  │         │ (uniform     │       │ (filesystem, │
  │          │         │  shape)      │       │  bulk, pipe) │
  └──────────┘         └──────────────┘       └──────────────┘
```

## Roadmap

* ✅ **0.1** — auth (login / status / logout) and `--help`.
* ✅ **0.2** — notes core (list / search / get / transcript) plus MCP-shape transcript JSON, parsed examples, first test suite.
* ✅ **0.3** — package hygiene (whitelist publish, sourcemaps stripped), `tiro mcp info` / `tiro mcp install`, ships `AGENTS.md`, paragraph-level transcript timestamp + `--no-timestamps`, redesigned OAuth callback page.
* ⏳ **0.4** — `notes export` (bulk → directory + manifest), templates, share-links, folders, `tiro schema` self-describe.
* ⏳ **1.0** — stable. Public license, Homebrew tap, automated publish.

→ Continue to [Setup](/en/developers/cli/setup) to install and authenticate.

## Links

* npm: [npmjs.com/package/@theplato/tiro-cli](https://www.npmjs.com/package/@theplato/tiro-cli)
* GitHub: [github.com/plato-corp/tiro-cli](https://github.com/plato-corp/tiro-cli)
* Changelog: [CHANGELOG.md](https://github.com/plato-corp/tiro-cli/blob/main/CHANGELOG.md)
* Issues: [github.com/plato-corp/tiro-cli/issues](https://github.com/plato-corp/tiro-cli/issues)