CLI ガイド

nolto CLI は、ターミナルから Nolto の MCP サーバーを操作する薄いクライアントです。npm パッケージ @nolto/cli として配布され、CI/CD パイプラインや Claude Code / Codex プラグインの基盤として機能します。

インストールと初回セットアップ

Node.js 20.11 以上が必要です。インストール不要で npx から実行できます:

npx @nolto/cli init

インストールした場合のコマンド名は nolto です（以降の例はインストール済みの表記）:

npm install -g @nolto/cli
nolto init

対話的なプロンプトが表示されます:

1. Base URL: デフォルトは https://nolto.app（変更不要な場合はそのまま Enter）
2. API トークン: 入力は非表示（* で表示）
3. デフォルトプロジェクト: トークンが検証された後、プロジェクト一覧から選択

設定は ~/.config/nolto/config.json（パーミッション 0o600）に保存されます。

トークン発行

API トークンは 設定 > API トークン で発行します。

コマンドリファレンス

設定・確認

リポジトリ紐付け

リポジトリ root に nolto.json を置くと、そのリポジトリ内のすべての CLI コマンドが自動的に正しいプロジェクトを参照します。チームでリポジトリをクローンした全員に共有されます。

nolto.json の形式:

{ "projectId": "00000000-0000-0000-0000-000000000001" }

nolto.json があれば --project フラグや NOLTO_PROJECT 環境変数を省略できます。

プロジェクト管理

プラン管理

plan register の主なオプション:

nolto plan register --file PLAN.md \
  --title "機能実装計画" \
  --status not_started \
  --doc plan=PLAN.md \
  --doc test_report=test-results.md \
  --no-git

フェーズ管理

ドキュメントアップロード

nolto doc upload <planId> --file report.md --kind test_report

環境変数と設定ファイル

環境変数（優先度順）

設定ファイル

~/.config/nolto/config.json（または $XDG_CONFIG_HOME/nolto/config.json）:

{
  "token": "nolto_user_...",
  "baseUrl": "https://nolto.app",
  "defaultProjectId": "00000000-0000-0000-0000-000000000001"
}

優先度: コマンドラインフラグ > 環境変数 > nolto.json（リポジトリ紐付け） > 設定ファイル > デフォルト値

終了コード一覧

レート制限の目安

Nolto MCP サーバーはユーザーあたり 60 リクエスト/分 のレート制限があります。CLI の 1 コマンドあたり約 3 HTTP ラウンドトリップ（initialize + initialized + tools/call）を消費するため、実効スループットは 約 20 コマンド/分 です。

429 エラーが発生した場合は、メッセージに含まれる Retry-After 秒数を待ってから再試行してください。

オフラインキュー (nolto queue)

nolto queue はトークン不要のオフラインコマンドです。進捗情報をプロジェクトディレクトリの .nolto/pending.jsonl に追記し、後で nolto flush でまとめて送信できます。Claude Code の Stop フックと組み合わせて、セッション終了時の自動送信に使うことが主な用途です。

4 つのサブコマンド

有効な <status> 値: not_started / in_progress / done / discarded
有効な <verdict> 値 (phase-test): passed / failed / skipped
有効な <verdict> 値 (plan-review): go / no_go

キューファイルの場所

<projectDir>/.nolto/pending.jsonl（1 エントリ 1 行の JSONL 形式）。

<projectDir> の解決順序（優先度順）:

1. --queue-dir <path> フラグ
2. NOLTO_QUEUE_DIR 環境変数
3. CLAUDE_PROJECT_DIR 環境変数（Claude Code が自動設定）
4. 最も近い .git ディレクトリを持つ祖先ディレクトリ
5. 最も近い .nolto ディレクトリを持つ祖先ディレクトリ
6. カレントディレクトリ (process.cwd())

キューの上限は 200 エントリ（QUEUE_MAX_ENTRIES）です。上限に達した場合は exit 2 で終了します。nolto flush でキューを空にしてから再度キューイングしてください。

フラッシュ (nolto flush)

nolto flush はキューに溜まったエントリを Nolto MCP サーバーに送信します。

同期モード（デフォルト）

nolto flush [--queue-dir <path>]

• キューの先頭から順に 1 件ずつ送信し、成功するたびにキューファイルを書き換えます（原子的リネーム）。
• 失敗（ネットワークエラー・429 など）が発生した時点で停止し、残りのエントリはキューに保持します。
• 常に exit 0 を返します（v0.2.0）。失敗はキューに残り、.nolto/flush.log に記録されます。
• JSON サマリー出力 (--json): { flushed: number, remaining: number, failed: 0 | 1 }

デタッチモード (--detach)

nolto flush --detach

バックグラウンドワーカーを二重フォーク（spawn detached + unref）して即座に exit 0 します。Claude Code の Stop フックはこのモードで起動されます。

障害時の動作

ロックファイル

同時実行を防ぐため .nolto/flush.lock に PID を書き込みます。別プロセスがロックを保持している場合は何もせず exit 0 します。プロセスが異常終了した場合（stale PID）は次回起動時に自動的にロックを引き継ぎます。

JSON 出力モード

--json フラグを付けると、すべての出力が JSON 形式になります（結果は stdout、エラーは stderr）:

nolto plan list --json | jq '.[] | .id'

エラー時の stderr 形式:

{
  "error": {
    "message": "Unauthorized",
    "exitCode": 3,
    "status": 401,
    "hint": "Run `nolto init` to configure a token, or set the NOLTO_TOKEN environment variable."
  }
}

フィールド: message（文字列）、exitCode（数値）、status（HTTP ステータスコード、HTTP エラー時のみ存在）、hint（任意のガイダンス）。