CLI ガイド

@nolto/cli は、リポジトリの .nolto/roadmaps/<slug>.json と関連する Markdown 文書を Nolto に同期するクライアントです。

インストール

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

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

コマンド一覧

これ以外の旧 plan 操作コマンドは提供していません。進捗の更新はリポジトリ内の roadmap-progress skill が .nolto/roadmaps/<slug>.json を変更し、CLI が同期します。

nolto init

nolto init
nolto init --force

Base URL と API token を確認し、既存 project の選択または新規 project の作成を行います。Git リポジトリ内では nolto.json、roadmap の雛形、roadmap-progress skill、watch registry も設定します。 リポジトリ内で再実行した場合は保存済み token を維持してリポジトリ設定のみを行い、--force を指定するとグローバル設定を再構成します。 インストール済みの roadmap-progress skill と CLI のバージョンが異なる場合は同期・監視時に警告され、リポジトリ内で nolto init を再実行すると更新できます。

nolto login

nolto login
nolto login --force

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

nolto whoami

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. .nolto/roadmaps/*.json をファイル名順に列挙し、それぞれを検証
3. フェーズ／タスクの plan が参照する文書を読み込み
4. ファイル名の stem を slug として、各 roadmap と文書を冪等に PUT

サーバー上の source_updated_at より古い roadmap は 409 Conflict で拒否されます。別環境の新しい更新を上書きしないための保護です。

ロードマップの削除

Web UI のロードマップ詳細ページから削除できます。先にローカルの .nolto/roadmaps/<slug>.json を削除してコミットしてください。ファイルが残っていると、次回の nolto sync または nolto watch で再作成されます。

nolto diff

nolto diff
nolto diff <slug>

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

nolto pull

nolto pull
nolto pull <slug>
nolto pull --merge
nolto pull --merge <slug>

サーバーの roadmap を検証して .nolto/roadmaps/ に取得します。同名のローカルファイルは確認なしで上書きしますが、ローカルだけに存在する roadmap は削除しません。--merge を付けると、検証済みのローカル roadmap とサーバー版を構造的に merge します。実行後はコミット前に git diff で確認してください。

roadmap の conflict 解消（merge driver）

nolto init は .nolto/roadmaps/*.json 用の Git merge driver をリポジトリ単位で設定します。すでに初期設定済みのリポジトリでも nolto init を再実行すれば設定されます。Git の conflict 時は phase と task を ID で照合し、nolto merge-file が構造的に merge します。

push 前は次の順で差分を確認できます。

nolto diff
nolto pull --merge   # サーバー側の変更も取り込む必要がある場合
git diff
nolto sync

nolto watch

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

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

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

設定と優先順位

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

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

終了コード