CLI を 5 分で動かす

tansr は開発者向けのエージェント CLI です。同じ 1 つのカーネルを、対話式ターミナル（TUI）、ヘッドレススクリプト（headless）、常駐サービス（serve）、エディタエージェント（acp）、MCP ツールサービス（mcp serve）の 5 つの形態で提供します。このページでは最短経路だけを進みます：インストール、ログイン、ひと言話す、イベントストリームを一度見る。現在のバージョンは 0.10.3（npm @tansr/cli、2026-10-10 公開。0.10.2 / 0.10.3 は新しい @tansr/serve をインライン化しただけで、コマンド、フラグ、ACP 面は 0.10.1 と同じです）です。

前提

Node.js ≥ 22.19（npm パッケージ形態）。単一ファイル実行版（SEA、Node ランタイム同梱）は現時点では Linux x64 / arm64 の 2 種類だけです。後述を参照してください。
Windows / macOS / Linux をサポートします。Windows では Windows Terminal を推奨します。従来の conhost では自動的に ASCII グリフ段階に切り替わりますが、機能に影響はありません。

インストール

npm i -g @tansr/cli
tansr --version          # 0.10.3

パッケージ名は @tansr/cli、コマンド名は tansr です。アップグレードも同じく npm i -g @tansr/cli@latest で行います。0.10.1 以降、インストールした各バージョンの初回起動時にユーザーキャッシュディレクトリへ約 2 MB の Node コンパイルキャッシュを書き込みます（同じバージョンの 2 回目以降の起動が速くなります。TANSR_COMPILE_CACHE=0 で無効化できます。設定と doctorを参照）。

単一ファイル形態（SEA）：Linux の 2 種類を公開中。 公式配布サイト https://bash.tansr.com の stable チャネルでは 2026-10-05 以降、tansr-sea-linux-x64 と tansr-sea-linux-arm64（glibc ≥ 2.28）を配布しており、現在は 0.10.3（2026-10-10、npm パッケージと同じソースからビルド）です。Windows 版はコード署名証明書が整うまで掲載せず、macOS 版は Apple Developer 証明書と公証待ち、musl / alpine は SEA の約束の対象外です——これらのプラットフォームでは npm パッケージを使ってください。インストールは「ダウンロード → 検証 → 配置」の 3 ステップのスクリプトで行い、まずダウンロードして内容を確認してから実行します：

curl -fsSLO https://bash.tansr.com/install.sh
sh install.sh            # 可选参数 stable|beta;缺省落位 ~/.local/bin/tansr

スクリプトはチャネルの SHA256SUMS と実測ハッシュを比較し、一致しなければファイルを削除してインストールを拒否します。TANSR_INSTALL_DIR / TANSR_CHANNEL でデフォルトを上書きできます。SEA でインストールした後の tansr update（--install を付けたときだけインストール）は、デフォルトで配布サイトの署名付きエンベロープ release/{channel}/sea/latest.signed.json を読み、内蔵の公開鍵（release-signing-v1）で検証してからバージョンを比較します。npm でインストールした場合の tansr update は npm レジストリを照会し、この経路は使いません。

認証情報：個人アクセストークンでログイン

CLI はプラットフォームモードで動きます。ログイン後、モデル一覧と料金表はプラットフォームから配信されるので、provider 設定を手で書く必要はありません。

コンソールで個人アクセストークン（PAT）を作成します。
初期化ウィザードを実行し、案内に従って PAT を貼り付けます（マスク入力で、エコーバックされません）。

tansr init

ウィザードは本人確認を行い、このマシン用のアプリ認証情報を派生させ、それを OS のキーチェーンに書き込みます（使えない場合は権限 0600 のファイルにフォールバックし、明示的に通知します）。最後にサマリーカードを表示します：アカウント指紋、残高、最近の使用量、利用可能なモデル数、派生キーの有効期限。この過程でモデル呼び出しは一切発生せず、何度でも実行できます。

スクリプトや CI で対話なしに実行するには：

TANSR_PAT=<PAT> tansr init

tansr init --pat <PAT> でも直接値を渡せますが、シェルの履歴に残るため推奨しません。

ログアウトは tansr logout です。このマシンの認証情報を消去し、このマシンの派生キーの無効化を試みます。PAT 自体は取り消されません（他のデバイスがまだ使っている可能性があるためです）。

最初のセッション

tansr をそのまま実行すると対話式ターミナルに入ります。

tansr

起動時にウェルカムバナーと「基本設定サマリー」（ログイン ID、ポータルアドレス、現在のモデル、コンテキスト方式、残高）が表示されます。入力欄に文字を打って Enter を押せば対話できます。@ でワークスペースのファイルを参照し、/ でスラッシュコマンドを呼び出します。初日から使うコマンドをいくつか挙げます。

コマンド	役割
`/help`	すべてのコマンドを一覧表示
`/status`	バージョン / 言語 / セッション / モデル
`/model`	モデルセレクターを開く。`/model <エイリアス>` で直接切り替え
`/cost` `/usage`	このセッションのコストと token 使用量
`/doctor`	アセンブリ状態の自己診断
`/quit`	終了

Esc で現在のターンを中断、Ctrl+T でフルスクリーンのトランスクリプト表示、Ctrl+C も中断です。

イベントを見る

ヘッドレスモードではすべてがイベントです。-p に prompt を 1 文渡して --json を付けると、1 行 1 JSON の NDJSON イベントストリームが得られます。ストリームの末尾には必ず type: "result" のサマリーが 1 件あります。

tansr -p "用一句话介绍这个目录" --json

{"type":"result","reason":"completed","exitCode":0,"usage":{"inputTokens":1200,"outputTokens":300}}

イベントのエンベロープフィールドは type / sessionId / seq / ts / v / source です。主なイベントファミリーは session.*、turn.*、msg.*、tool.*、agent.*、hook.*、cost.*、mcp.*、plan.*。終了コードの意味：0 成功、1 モデルまたは内部エラー、2 中断、3 上限到達（ターン数 / 予算）、4 prompt が長すぎる、5 用法エラー。

Node でこのストリームを消費するのは数行で済みます。

import { createInterface } from 'node:readline';
import { spawn } from 'node:child_process';

const child = spawn('tansr', ['-p', '总结本仓库', '--json'], { stdio: ['ignore', 'pipe', 'inherit'] });
for await (const line of createInterface({ input: child.stdout })) {
  const ev = JSON.parse(line);
  if (ev.type === 'msg.text.delta') process.stdout.write(ev.text);
  if (ev.type === 'result') console.log('\n退出码:', ev.exitCode, '原因:', ev.reason);
}

ヘッドレスモードには問い合わせのチャネルがありません。権限判定が「ユーザーに確認」になった場合は一律で拒否にフォールバックします（fail-closed）。権限を開くには --allowedTools "Shell(git *),Read" のようなセッション単位のルールを使うか、--permission-mode で初期モードを指定してください。

最初によくつまずく点

現象	対処
「TUI には対話式ターミナル（TTY）が必要です」	パイプの中で `tansr` を起動しています。非対話の場面では `-p` を使う
初期化せずに起動した	空状態のガイドカードに入ります。その場で `/init` と入力すればログインできます。無人運転の形態では終了コード 5 で終了し、`tansr init` を促します
残高がゼロ	サマリーカードが警告しますが、処理は止めません。プラットフォームのモデル呼び出しはサーバー側の課金ゲートで拒否され、ローカル機能には影響しません
プラットフォームをまったく使いたくない	`TANSR_ESCAPE_LOCAL=1` を設定し、ユーザーマニュアルに従って `.tansr/settings.json` にローカル provider を設定する

次のステップ

設定と doctor：5 層の設定、よく使う環境変数、tansr doctor の各セクションの読み方。
コマンドとフラグのリファレンス：すべてのサブコマンドとフラグ。
自分のエージェントを他の人にも使わせたい？セッションサービスを 5 分で動かすをご覧ください。CLI 形態の tansr serve --v2 は 0.10.0 以降、統一呼び出し面 /api も同時にマウントします（新規の統合はこちらへ）。--v2 構成では /v1 面はデフォルトで無効になり、移行用フラグ --legacy-v1 は 0.10.1 以降は非推奨です。0.10.2 以降は環境変数 TANSR_SERVE_LEGACY_PREFIX（デフォルト readwrite、0.10.3 でも変更なし）で旧 /v2、/v3/* プレフィックスの廃止ウィンドウを制御できます。詳しくはデプロイと認証を参照してください。