Tiro CLI for AI agents

Claude Code, Cursor, ChatGPT 에이전트에서 MCP와 CLI를 언제 써야 하는지 설명해요.

멘탈 모델

MCP 결과는 대화에 남고 CLI 결과는 파일로 저장할 수 있어요.

MCP get_note_transcript를 호출하면 전체 전사(노트당 보통 5~50KB)가 대화 컨텍스트에 들어와요. 요약하거나 컨텍스트를 정리하기 전까지 이후 대화에도 남아요. tiro notes transcript --output transcript.md를 호출하면 같은 내용을 파일로 저장하고 stdout에는 메타데이터 한 줄만 반환해요.

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

전사 100개도 대화에는 경로와 개수만 남길 수 있어요. 필요한 파일만 읽으세요.

도구 선택 치트시트

이럴 때…	사용	비고
주제로 노트 찾기	MCP `search_notes`	주요 문서 포함, 응답은 대화에 남음
노트 50개 이상 파일로 저장	CLI `tiro notes search "…" --json > meetings.jsonl`	NDJSON 파이프, `jq`로 필터링
그대로 인용하기	MCP `get_note_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

대화에는 stdout 3줄과 메타데이터 12개만 남아요(약 80토큰). 전사 12개는 ./out/에 저장돼요. 정확한 표현이 필요할 때만 Read 도구로 하나씩 읽으세요. get_note_transcript를 12번 호출하면 60~~600KB(전사 12개 × 각 5~~50KB)가 대화에 남아요. 자세히 볼 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

홈

시작하기

API

웹훅

MCP

CLI

개발자 리소스

AI 에이전트를 위한 가이드

멘탈 모델

도구 선택 치트시트

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

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

에러를 JSON으로 읽기

Exit code

출력 보장

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

링크

​멘탈 모델

​도구 선택 치트시트

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

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

​에러를 JSON으로 읽기

​Exit code

​출력 보장

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

​링크

멘탈 모델

도구 선택 치트시트

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

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

에러를 JSON으로 읽기

Exit code

출력 보장

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

링크