Tiro CLI for AI agents

Tiro 데이터가 필요한 Claude Code·Cursor·ChatGPT 에이전트를 만들고 있다면, 이 페이지가 어떤 surface를 언제 호출할지와 컨텍스트 윈도우를 가볍게 유지하는 법을 알려줘요.

멘탈 모델

MCP는 컨텍스트로 반환하고, CLI는 디스크로 반환해요.

MCP get_note_transcript를 호출하면 전체 transcript 텍스트(노트당 보통 5~50 KB)가 대화 컨텍스트 윈도우에 주입돼요. 이후 모든 턴이 compaction이나 요약 전까지 그 무게를 계속 짊어지게 돼요. tiro notes transcript --output transcript.md를 호출하면 같은 내용이 디스크에 저장되고, stdout에는 메타데이터 한 줄만 반환돼요:

{"ok":true,"data":{"saved":"./transcript.md","size":12450,"format":"md","guid":"note-a8f2c1…","paragraphCount":42,"segmentCount":127}}

transcript 100개라면 50 KB가 약 50 토큰(경로 + 개수)으로 줄어요. 필요할 때만 각각 읽으면 돼요.

도구 선택 치트시트

이럴 때…	사용	비고
주제로 노트 찾기	MCP `search_notes`	primary document가 함께 hydrate됨, 컨텍스트에 남음
노트 50개 이상 디스크로	CLI `tiro notes search "…" --json > meetings.jsonl`	NDJSON 파이프, `jq`로 쉽게 자름
그대로 인용하기	MCP `get_note_transcript`	작은 일부만, 토큰 많이 듦
전체 transcript 나중을 위해 저장	CLI `tiro notes transcript <guid> --output <path>`	내용은 디스크, 메타데이터는 stdout
날짜별로 회의 둘러보기	CLI `tiro notes list --since 7d --json`	가벼움, 메타데이터만
MCP 호스트 없이 MCP 형태 JSON 읽기	CLI `tiro notes transcript <guid> --format json`	MCP `get_note_transcript`와 바이트 단위로 동일

MCP를 호출할지 CLI를 호출할지

Are you in an MCP-aware client (Claude Desktop, Cursor, Code)?
│
├─ NO  → CLI is your only option. Use --json everywhere.
│
└─ YES → Will the result fit comfortably in your context window?
         (Rule of thumb: <5 KB total, single-shot reasoning)
         │
         ├─ YES → MCP. Schema-typed call, multi-turn friendly.
         │
         └─ NO  → CLI with --output. Disk holds the content,
                  context holds the path. Reach for Read tool
                  on demand.

예제 — 최근 30일 ‘Acme Corp’ 회의

클라이언트별 분기 요약본을 작성하려고 해요. 최근 30일 동안 Acme가 언급된 모든 회의를 전체 transcript와 함께 가져와야 해요.

# 1. Search → metadata + hydrated documents (NDJSON)
tiro notes search "Acme Corp" --since 30d --json > /tmp/acme.jsonl
# stdout: ~12 lines of NDJSON, ~3 KB total

# 2. Pull guids without loading bodies
cat /tmp/acme.jsonl | jq -r '.guid' > /tmp/guids.txt

# 3. Download each transcript to disk (paths only return to context)
xargs -I{} tiro notes transcript {} --output ./out/{}.md < /tmp/guids.txt

누적 컨텍스트 비용: 약 80 토큰(stdout 3줄 + 메타데이터 ack 12개). 이제 회의 transcript 12개가 ./out/에 있어요. 정확한 표현이 필요할 때만 Read 도구로 하나씩 읽으면 돼요. MCP만 쓰는 경우와 비교해 보면, get_note_transcript를 12번 호출하면 60~~600 KB(transcript 12개 × 각 5~~50 KB)가 컨텍스트에 주입돼요. 대부분은 불필요한 무게예요. 실제로 자세히 봐야 하는 건 2~3개뿐이거든요.

에러를 JSON으로 읽기

CLI의 모든 에러는 안정적인 envelope을 따라요:

{
  "ok": false,
  "error": {
    "code": "auth_required",
    "message": "Not authenticated. Run `tiro auth login` to sign in, or set TIRO_TOKEN env var.",
    "suggestion": "tiro auth login",
    "errorType": "auth_required",
    "httpStatus": null,
    "requestId": null
  }
}

안정적인 필드:

필드	용도
`error.code`	machine-readable 식별자, 이걸로 분기
`error.errorType`	큰 분류(`unauthorized`, `not_found`, `bad_request`, …)
`error.suggestion`	자동 복구를 위해 실행할 바로 그 명령
`error.httpStatus`	해당되는 경우 upstream HTTP status
`error.requestId`	지원 에스컬레이션용 upstream `x-request-id`

error.message는 사람이 읽는 용도이고 릴리스마다 표현이 바뀔 수 있으니, 이걸로 패턴 매칭하지 마세요.

Exit code

Code	의미	에이전트 동작
`0`	성공	계속
`1`	일반 에러	`error.code` 확인
`2`	usage 에러(잘못된 flag, 잘못된 날짜, 필수 인자 누락)	호출을 고침, 무작정 재시도 금지
`4`	auth 필요	`tiro auth login` 실행 후 재시도
`64`	EX_USAGE	`2`와 동일
`65`	EX_DATAERR	응답이 schema 검증 실패, 사용자에게 알림
`78`	EX_CONFIG	env·keychain에 token 없음, 사용자에게 인증 요청 또는 `TIRO_TOKEN` 제공 요청

셸에서 빠른 auth 복구 루프:

output=$(tiro notes list --json 2>&1)
exit_code=$?
if [ $exit_code -eq 4 ] || [ $exit_code -eq 78 ]; then
  tiro auth login
  output=$(tiro notes list --json)
fi
echo "$output"

출력 보장

--json은 스트림에서 NDJSON — list와 search는 한 줄에 JSON 객체 하나씩 내보내요. 페이지네이션 cursor는 마지막에 {"_cursor": "…"} 줄로 와요.
--output <path>는 원자적으로 씀 — temp 파일 + rename 방식이라 절대 부분 저장이 없어요.
TTY 자동 감지 — 인터랙티브 셸에선 pretty, 파이프·리다이렉트되면 JSON. --pretty / --json으로 강제할 수 있어요.
tiro notes transcript --format json은 MCP get_note_transcript와 일치 — 같은 필드명, 같은 중첩, 같은 speaker-segment 구조예요. 기존 파서를 그대로 재사용하세요.
token은 절대 출력되지 않음 — auth status는 앞 4자만 보여주고, --verbose에서도 나머지는 가려져요.

안정 계약 — patch 릴리스에서 깨지지 않는 것

error.code 값
error.errorType 값
Exit code
list/search의 NDJSON 줄 형태
tiro notes transcript --format json이 반환하는 MCP 형태 JSON
--output 작업이 반환하는 메타데이터 줄 형태

그 외(pretty 출력, 에러 메시지, verbose 로그 포맷)는 best-effort이고 바뀔 수 있어요.

링크

Quickstart — 직접 해보는 다섯 가지 시나리오.
Setup — 설치 + 인증 + headless/CI 설정.
CLI on npm
tiro-cli on GitHub
CHANGELOG

​멘탈 모델

​도구 선택 치트시트

​MCP를 호출할지 CLI를 호출할지

​예제 — 최근 30일 ‘Acme Corp’ 회의

​에러를 JSON으로 읽기

​Exit code

​출력 보장

​안정 계약 — patch 릴리스에서 깨지지 않는 것

​링크