Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api-docs.tiro.ooo/llms.txt

Use this file to discover all available pages before exploring further.

The Tiro CLI is published on npm as @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 Node.js

​
Quick install

npm install -g @theplato/tiro-cli

tiro auth login                                 # browser opens; OAuth + PKCE
tiro notes search "Q3 Planning" --since 7d --json

​
When to use which surface

REST APIMCP serverCLI
Audienceservices, integrationsMCP-aware AI clientsshells, CI, ad-hoc agents
Result lands inyour codeagent context windowfilesystem or stdout pipe
Per-session token costper requestthousands (tool schema)dozens (per call)
Best forservice-to-service trafficsmall reads, multi-turn reasoningbulk export, file ops, scripting
DiscoveryOpenAPIMCP list_toolstiro --help
The three surfaces share the same OAuth provider and JWT audience, so credentials issued for one work on the others. See Authentication.
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.

​
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.
  • 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 (Kotlin) — /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 to install and authenticate.