CLI ガイド

@nolto/cli は、Nolto の roadmap と、リポジトリにある関連する Markdown 文書を同期するクライアントです。roadmap の正本はサーバーにあり、手元の JSON は nolto roadmap path [slug] が返すリポジトリの外のキャッシュです。Git では管理しません。

インストール

npm install -g @nolto/cli
nolto --version

Node.js 20.11 以上が必要です。

コマンド一覧

これ以外の旧 plan 操作コマンドは提供していません。進捗は roadmap-progress skill が nolto roadmap start / done / block / todo <task> でサーバーに直接書きます。

nolto init

nolto init
nolto init --force

Base URL と API token を確認し、既存 project の選択または新規 project の作成を行います。Git リポジトリ内では、nolto.json への紐付け、skill(roadmap-progress・project-memory)のインストール、メモリの hook、project へのリポジトリの登録、roadmap のキャッシュ、watch registry への登録も行います。このリポジトリの roadmap がサーバーに無ければ作成します。 リポジトリ内で再実行した場合は保存済み token を維持してリポジトリ設定のみを行い、--force を指定するとグローバル設定を再構成します。 インストール済みの roadmap-progress skill と CLI のバージョンが異なる場合は同期・監視時に警告され、リポジトリ内で nolto init を再実行すると更新できます。

nolto login

nolto login
nolto login --force

ブラウザで CLI を承認し、Personal API Token を設定ファイルへ保存します。別端末のブラウザでも承認できます。

nolto whoami

トークン情報の取得に成功すると scopes（全権限は full）と対象 project を表示し、JSON に tokenScopes / tokenProject を追加します。取得失敗は非致命です。

nolto whoami
nolto --json whoami

Base URL、token の末尾、project binding の解決元、参加 project 数を表示します。

nolto link

nolto link <projectId>
nolto link --show
nolto link --rebind [--yes]
nolto link --unlink

リポジトリ root の nolto.json に project ID を保存します。チームで同じ同期先を使うため、token を含まない nolto.json はコミットしてください。

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

リポジトリの紐付け

1 つの Nolto プロジェクトは 1 つのリポジトリ（git remote get-url origin を正規化したもの。remote が無い場合はこのマシンの ID とパス）に紐付きます。最初に nolto sync したリポジトリで確定し、別のリポジトリからの同期は 409 repo_mismatch で拒否されます。

紐付け状態はプロジェクトの「設定」→「リポジトリ連携」で確認・解除できます。

• 確認: nolto link --show
• 付け替え（オーナーのみ、7 日に 1 回）: まず nolto link --show で projectId がこのリポジトリ用か確認し、正しいリポジトリで nolto link --rebind
• nolto link --rebind はプロジェクト名を表示して確認します。プロンプトを省略する場合は --yes（-y）を付けてください。
• 0.8.0 より前の CLI は 426 で同期できません。nolto update で更新してください。

nolto sync

nolto sync

同期処理は次の順に実行されます。

1. nolto.json または設定から project ID を解決
2. キャッシュの roadmap を slug 順に列挙し、それぞれを検証(別のリポジトリの roadmap は飛ばす)
3. フェーズ／タスクの plan が参照する文書を読み込み
4. キャッシュの revision を基準(baseRevision)にして各 roadmap と文書を PUT し、結果をキャッシュに書き戻す

サーバー側の変更と衝突した場合や、基準の revision が期限切れの場合は 409 Conflict で止まります。nolto pull で取り直し、変更をやり直してから再度同期してください。

ロードマップの削除

Web UI のロードマップ詳細ページから削除できます。手元のキャッシュ(nolto roadmap path <slug> の JSON)は消えないので、削除のあとに消してください。残っていると、次の nolto sync が baseRevision が不正です。 で止まります。

roadmap 同期後、直近 300 コミットを git log --no-color --format=%H%x1f%s%x1f%an%x1f%cI -n 300 で読みます。件名の \b([A-Z][A-Z0-9]{1,9})-([1-9][0-9]{0,8})\b を課題キーとして重複除去し、末尾 (#123) または先頭 Merge pull request #123 は PR としても送ります。キー無しは送信しません。1 行のキーを 20 個ずつ、リクエストを 500 行ずつに分割し、件名・作者は 500 文字までにします。

毎回同じ範囲を読み、サーバー側 unique で重複を除きます。roadmap:sync トークンと git_links プロジェクトスコープが必要です。取り込み失敗は警告のみで roadmap 同期は成功扱いです。nolto sync --no-git-links または NOLTO_GIT_LINKS=0 で無効化できます。watch も同期時に同じ環境変数を参照します（Git の変更だけでは watch を起動しません）。Git 不在・非リポジトリはスキップします。ログは git links: linked N (existing M, skipped K) で、新規登録・既存リンク・未解決キーを区別します。sync --json は gitLinks: { linked, existing, skipped } | null を返します。

nolto diff

nolto diff
nolto diff <slug>

キャッシュとサーバーの roadmap を変更せずに比較します。nolto sync で push する前の確認に利用でき、差分がある場合は終了コード 1、差分がない場合は 0 を返します。

nolto pull

nolto pull
nolto pull <slug>
nolto pull --force

サーバーの roadmap を検証してキャッシュに取得します。slug を省略すると、すべての roadmap を取得します。同期していない変更がキャッシュにある roadmap は、警告を出して飛ばし、エラーで終わります。その変更を捨てて上書きするときは --force を付けます。nolto roadmap pull も同じ動作です。

nolto roadmap

roadmap の正本は Nolto のサーバーです。リポジトリに置くのは nolto.json だけで、roadmap の JSON は nolto roadmap path [slug] が返すリポジトリの外のキャッシュにあります。

進捗は roadmap-progress skill が nolto roadmap start / done / block / todo <task> でサーバーに直接書きます。フェーズや task の追加など構造を変えるときは、キャッシュの JSON を編集し、検証してから同期します。nolto watch が常駐していれば、編集を検知して自動で同期します。

nolto roadmap path       # キャッシュの JSON の場所
nolto roadmap validate
nolto roadmap sync

旧形式のリポジトリ(.nolto/roadmaps に roadmap がある)では、nolto sync などが「Run nolto roadmap migrate」で止まります。nolto roadmap migrate で roadmap をサーバーとキャッシュに移してください。終わると後片付けのコマンド(git rm -r .nolto/roadmaps や、merge.nolto-roadmap.* の git config の削除)を表示するので、自分で実行します。

nolto watch

nolto watch
nolto watch --debounce 1000
nolto watch --install-service

nolto init で登録された全リポジトリを監視します。キャッシュの roadmap または参照文書が変わると、debounce 後に同期します。

Linux では --install-service で systemd user unit nolto-watch をインストールして常駐化できます。

nolto issue

課題の検索・起票・更新を CLI から行います。共通の --project <id> と --json を使えます。project は flag → NOLTO_PROJECT → 親方向に探索した nolto.json → config の順で解決し、git は不要です。

下書きは API トークンの持ち主にだけ見えます。詳しくは課題の下書きをご覧ください。

状態・種別・カテゴリは名前（大文字小文字を区別しない完全一致）または UUID で指定し、不一致・曖昧な名前は候補付きでエラーになります。担当者は me / none / UUID。priority は high / normal / low、due は YYYY-MM-DD です。list の sort は updated / due / priority / number / created / assignee / status / type / subject、order は asc / desc、page は正の整数、parent は課題キー・番号または none です。

create --type で本文を省略すると種別のテンプレートを使い、human 出力に body: from template と表示します。close は sortOrder が最小の終了状態を選び、指定した状態が終了状態でなければ失敗します。課題キーは番号部分だけを API に送るため、prefix が違っても選択プロジェクト内の同番号の課題を指します。

create --phase は作成したキーをローカル roadmap の task ID の issues に追記します。複数ファイルがあれば --roadmap <slug> が必要です。重複は追加せず、変更時は schema v2 とタイムゾーン付き updatedAt を保存します。その後 nolto sync を実行してください。ローカル更新の失敗時にも課題は作成済みです。エラーに示したキーでリンクを修復し、再起票しないでください。

nolto issue list --q "ログイン" --closed include
nolto issue create --subject "ログイン不具合" --phase r4.t2
nolto issue create --draft --subject "文言を直す" --body-file notes.md
nolto issue publish <draft-id>
nolto sync
nolto issue update NOLTO-12 --status "処理中" -m "再現して修正中"
nolto issue close NOLTO-12 -m "回帰テストで検証済み"

--json は API 応答を保持します。list は issues/total/page/pageSize、view は課題 bundle、create は issue、update/close は issue/comment、comment は comment を返し、create --phase 成功時だけ roadmap.file/taskId を追加します。HTTP 403 token_scope/token_project は exit 3 とトークン設定への案内、error 文字列付き 404 と 422 は exit 2（422 は details も表示）です。error 文字列のない 404 は従来どおり exit 5 です。

設定と優先順位

優先順位は、コマンドライン option、環境変数、nolto.json、ユーザー設定、既定値の順です。

ユーザー設定は ~/.config/nolto/config.json、または $XDG_CONFIG_HOME/nolto/config.json に保存されます。

終了コード