CLI コマンド一覧

nanoterm --help でコマンドツリー全体を表示できます。各サブコマンドも --help を受け付け、必ず 1 つは実例が付いています。エージェント向けの JSON カタログは nanoterm commands で取得できます。

グローバルフラグ

フラグ	説明
`--org <id>`	このコマンドだけアクティブ org を上書き（通常は `~/.nanoterm/config.json` / `NANOTERM_ORG_ID`）
`--json`	エラー時に stderr へ JSONL 1 行を出力（`kind`, `retryable`, `request_sent`, `attempt`, `status`, `code`）。エージェントのリトライ判断用

--json のフィールド構造は安定です。request_sent: false はリクエストがサーバーに届かなかった（ws create のような非冪等操作でも安全に再試行可能）。request_sent: true かつ retryable: true はサーバーに届いて副作用が発生した可能性があるため、エージェントは状態を確認してから再試行すべきです。

nanoterm --json ws create --image ghcr.io/momenntal/nanoterm-claude-code 2>err.jsonl
echo $?               # 終了コード
cat err.jsonl
# {"level":"error","kind":"network","retryable":true,"request_sent":false,"upstream":"ECONNREFUSED"}

auth

認証と API キーの管理。

`nanoterm auth login`

ブラウザを開いてサインインします。/cli-auth で認証すると、このマシン専用の API キーが発行され、~/.nanoterm/config.json（パーミッション 0600）に保存されます。CLI はコールバック用にワンショットのローカルポートで待ち受け、受信後または 5 分経過で終了します。

nanoterm auth login

`nanoterm auth set-key <key>`

API キーを CLI に保存します。

nanoterm auth set-key nt_a1b2c3d4...

`nanoterm auth status`

現在の認証状態を表示します。

nanoterm auth status
# Authenticated
#   API:    https://api.nanoterm.dev
#   Key:    nt_a1b2c3d4e5f6...
#   Config: /Users/you/.nanoterm/config.json

`nanoterm auth logout`

保存された認証情報をクリアします。

nanoterm auth logout

ws

ワークスペースの管理。

`nanoterm ws create`

新しいワークスペースを作成します。

フラグ	説明	デフォルト
`-i, --image <image>`	ベースイメージ	`ghcr.io/momenntal/nanoterm-claude-code`
`-s, --size <size>`	`small`, `medium`, `large`	`small`
`-n, --name <name>`	ワークスペース名	自動生成
`-p, --port <mapping...>`	`host:container` でホストポート固定、または `container` のみで自動採番	—
`--policy <id>`	ポリシーをアタッチ	—
`-r, --repo <url>`	`/workspace` にクローンする Git リポジトリ	—
`-b, --branch <branch>`	クローンするブランチ	デフォルトブランチ

# デフォルト Claude Code ワークスペース
nanoterm ws create

# イメージとサイズを指定
nanoterm ws create --image ghcr.io/momenntal/nanoterm-codex --size medium

# 作成時にリポジトリをクローン（GITHUB_TOKEN シークレット経由で認証）
nanoterm ws create --image claude-code --repo https://github.com/foo/bar.git

# 公開アプリ用にホストポートを固定
nanoterm ws create -p 13000:3000 -p 18080:8080

イメージが nanoterm-claude-code または nanoterm-codex の場合、出力にエージェント認証セットアップ（secrets auth-*）の案内が表示されます。詳細は下記 secrets を参照。

`nanoterm ws list`

すべてのワークスペースを一覧表示します。エイリアス: nanoterm ws ls

nanoterm ws list
# ID            NAME              STATUS      IMAGE
# ws_a1b2c3d4   my-agent          running     ghcr.io/momenntal/nanoterm-claude-code
# ws_e5f6g7h8   test-runner       stopped     ubuntu:22.04

`nanoterm ws ports <id>`

ホストポートマッピングと、ワークスペース内で自動検知されたリスナーを表示します。

nanoterm ws ports ws_a1b2c3d4
# Mapped (host → container URL):
#   CONTAINER   HOST URL
#   3000        http://localhost:13000
#
# Active listeners:
#   PORT    PROCESS       DETECTED
#   3000    next-dev      08:01:23
#
# Forward an unmapped port: nanoterm proxy ws_a1b2c3d4 <port>

`nanoterm ws stop <id>` / `start <id>`

stop はファイルシステムを保持して停止、start はそこから再開します。停止中はコンピュート課金もポーズします。

nanoterm ws stop ws_a1b2c3d4
nanoterm ws start ws_a1b2c3d4

`nanoterm ws rm <id>`

完全に終了・削除します。

nanoterm ws rm ws_a1b2c3d4
# ✓ Workspace removed

exec

ワンショットコマンドを実行します。stdout/stderr はターミナルに直接ストリームされ、CLI はコマンドの終了コードで終了します。

nanoterm exec <workspace-id> [flags] -- <command...>

フラグ	説明
`--cwd <path>`	ワークスペース内の作業ディレクトリ（デフォルト `/workspace`）
`--detach`	待たずにすぐ返す。`--log` と `nanoterm exec-wait` を併用
`--log <path>`	`--detach` 時の stdout+stderr を出力するワークスペース内ログファイル

フラグの位置は柔軟です。--cwd / --detach / --log はワークスペース ID の前後どちらにでも置けます。-- 以降がワークスペース内で実行するコマンドの始まりです。

# 以下 4 行は等価
nanoterm exec ws_a1b2c3d4 --cwd /workspace/api -- pnpm build
nanoterm exec --cwd /workspace/api ws_a1b2c3d4 -- pnpm build
nanoterm exec ws_a1b2c3d4 -- pnpm build
nanoterm exec --cwd=/workspace/api ws_a1b2c3d4 -- pnpm build

# 複数トークンのシェルパイプライン（bash -lc を使用）
nanoterm exec ws_a1b2c3d4 -- bash -lc "ls -la | head"

# バックグラウンドジョブ — 後述の exec-wait と組み合わせる
nanoterm exec ws_a1b2c3d4 --detach --log /tmp/build.log -- pnpm build

コマンドが終了コード 127 で、シェルワンライナー風（パイプ・リダイレクト・ &&）の形なら、CLI は nanoterm shell の利用を提案します。argv 形式ではなくシェル経由で実行したかったケースが大半だからです。

exec-wait

exec --detach（または shell --detach）したジョブの完了を待ち、ジョブの終了コードでこちらも終了します。detach ラッパーが書く sidecar ファイル <log>.exit をポーリングします。

nanoterm exec-wait <workspace-id> --log <path> [--interval <sec>] [--timeout <sec>]

nanoterm exec ws_a1b2c3d4 --detach --log /tmp/install.log -- npm install
nanoterm exec-wait ws_a1b2c3d4 --log /tmp/install.log
echo $?   # npm install の終了コード

なぜ ps -p <pid> ではなく sidecar ファイルなのか: detach した子プロセスはコンテナ内の PID 1（reap しない場合あり）に再ペアレントされ、<defunct> のまま残ることがあります。素朴な ps ポーリングはそこで永遠に終わりません。sidecar ファイルは正確に 1 度書かれ、ゾンビ状態の影響を受けないため、exec-wait が detach ジョブを待つための正規の方法です。

shell

ワークスペース内で対話的な bash セッションを開きます。exec と同じ通信路ですが bash -l PTY が事前構成されており、軽い試行や対話に便利です。

nanoterm shell ws_a1b2c3d4
# agent@ws-a1b2c3d4:/workspace$ ls

Ctrl+D で終了。

attach

ワークスペース内で動いている長時間プロセスのフル PTY に接続します。すでにワークスペースでフォアグラウンドのエージェントが走っていてその端末を引き取りたい場合に使います。

nanoterm attach ws_a1b2c3d4
# Connected. Press Ctrl+D to detach.

カラー、ウィンドウリサイズ、対話プログラム（vim, top など）に対応。新規シェルが欲しいだけなら nanoterm shell を推奨。

files

ワークスペース内のファイルの読み書き・コピー・追跡。

`nanoterm files cp <src> <dst>`

ファイルを双方向にコピーします。<id>: プレフィックス付きの引数がワークスペース側です。

# ローカル → ワークスペース
nanoterm files cp ./script.sh ws_a1b2c3d4:/workspace/script.sh

# ワークスペース → ローカル
nanoterm files cp ws_a1b2c3d4:/workspace/out.txt ./out.txt

nanoterm cp（トップレベル）は隠しエイリアスとして残されています。

すべての files cp / files write 操作は server 側で byte-verify されます。書き込み後に API が stat を実行して {bytes, mtime} を返し、 CLI が送信 byte と比較します。経路上のプロキシでサイレント truncate が起きた場合などは FILE_WRITE_BYTE_MISMATCH で大きく失敗します（ "アップロード成功"を装うことはありません）。

`nanoterm files write <id> <path>`

stdin の内容をワークスペース内のファイルに書き込みます。生成コンテンツをローカル一時ファイル無しでパイプしたいときに便利。

echo "hello" | nanoterm files write ws_a1b2c3d4 /workspace/hello.txt

cat config.yaml | nanoterm files write ws_a1b2c3d4 /etc/myapp/config.yaml

`nanoterm files tail <id> <path>`

ファイルの末尾をポーリングでストリームします。inotify ではなくポーリングなので、どのランタイムでも同じ挙動です。

nanoterm files tail ws_a1b2c3d4 /workspace/build.log

nanoterm tail（トップレベル）は隠しエイリアスとして残されています。

secrets

組織スコープのシークレット管理。保存時は暗号化、ワークスペース起動時に環境変数として注入されます。

`nanoterm secrets list`

nanoterm secrets list
# NAME                 TYPE   UPDATED
# ANTHROPIC_API_KEY    env    2026-04-15
# GITHUB_TOKEN         env    2026-04-12

`nanoterm secrets set <name>`

env 型シークレットを設定。値は --from-env（推奨）または stdin で渡す。 --value も可だがシェル履歴に残るため非推奨。

# 自分のシェル env から取得
nanoterm secrets set ANTHROPIC_API_KEY --from-env ANTHROPIC_API_KEY

# stdin
echo "$ANTHROPIC_API_KEY" | nanoterm secrets set ANTHROPIC_API_KEY --stdin

`nanoterm secrets rm <name>`

シークレットを削除。

`nanoterm secrets auth-claude`

Claude Code サブスクリプションの OAuth フローをサンドボックスワークスペース内で走らせ、生成された ~/.claude.json を組織シークレットに保存します。以後すべてのワークスペースに自動注入されます。

nanoterm secrets auth-claude
# ブラウザが開き、完了後に認証情報が保存されます

API キーで使う場合は env を直接設定:

nanoterm secrets set ANTHROPIC_API_KEY --from-env ANTHROPIC_API_KEY

`nanoterm secrets auth-codex`

OpenAI Codex CLI 認証。現状 --api-key のみ対応（ChatGPT サブスクリプションフローは未対応）。

nanoterm secrets auth-codex --api-key sk-...

`nanoterm secrets auth-github`

GitHub PAT を GITHUB_TOKEN シークレットとして保存します。 ws create --repo やワークスペース内の git 操作で利用されます。

`nanoterm secrets run -- <cmd>`

組織シークレットを環境変数にロードしてローカルコマンドを実行（infisical run の姉妹コマンド）。コマンドは あなたのマシンで動きます — エージェントが使うのと同じシークレットを必要とするローカルスクリプトに便利です。

nanoterm secrets run -- env | grep API
nanoterm secrets run -- pnpm dev

`nanoterm secrets status`

エージェントプロバイダー（Claude, Codex）の認証情報が組織に揃っているかを確認するサニティチェック。

snapshot

ローカル Podman ランタイム限定。実行中のコンテナをローカルイメージにコミットします。restore は 新しい ワークスペースをそのスナップショットから作成し、元のワークスペースは無傷です。

# コミット
nanoterm snapshot create ws_a1b2c3d4 --name before-migration

# 一覧
nanoterm snapshot list ws_a1b2c3d4

# 新規ワークスペースとして復元
nanoterm snapshot restore ws_a1b2c3d4 sn_x1y2z3

# ライブワークスペースとの差分
nanoterm snapshot diff ws_a1b2c3d4 sn_x1y2z3

# 削除（ローカルイメージも削除）
nanoterm snapshot rm ws_a1b2c3d4 sn_x1y2z3

proxy

未マッピングのコンテナポートをローカルマシンに転送します。ws create 時にポート固定できなかったアプリ（後から listen し始めるケース）に便利。

nanoterm proxy ws_a1b2c3d4 3000
# Forwarding http://localhost:3000 → ws_a1b2c3d4:3000 (Ctrl+C to stop)

転送候補となる検知済みリスナーは nanoterm ws ports <id> で確認可能。

起動時に proxy はワンショットの WebSocket 事前確認を行い、認証・ワークスペース存在・コンテナ到達性をチェックしてからローカル listener を開きます。upstream が 401/403 を返した場合や、ワークスペースが存在しない場合は明確なエラーで即終了 — 「:15173 で listen 中だが接続する度に 401」という紛らわしい状態にはなりません。

その他のコマンドグループ

存在し --help も完備していますが、ここでは簡潔に:

グループ	内容
`nanoterm keys ...`	API キーの作成 / 一覧 / 失効（dashboard の API Keys ページのミラー）
`nanoterm policy ...`	ガバナンスポリシーの作成 / 一覧 / 更新
`nanoterm members ...`	組織メンバー一覧、メール招待、招待取消
`nanoterm org current / switch <id>`	アクティブ org の表示 / 切替
`nanoterm billing plans / current / upgrade`	プランとクォータ使用量
`nanoterm audit list`	直近の監査ログ
`nanoterm commands`	全コマンド + フラグの JSON カタログ — エージェント用

自動アップデート通知

CLI は 1 日に 1 回だけ npm をチェックし、新しいバージョンがあれば 1 行のお知らせを表示します（次回起動時）。チェックはバックグラウンドかつネットワーク失敗時はサイレント — 実行コマンドをブロックしません。

API が 最低必要バージョンを上げた場合、サーバーから 426 CLI_VERSION_TOO_OLD が返ります（アップグレードコマンド付き）。 npm install -g @nanoterm/cli@latest を実行してリトライしてください。

グローバルフラグ​

auth​

nanoterm auth login​

nanoterm auth set-key <key>​

nanoterm auth status​

nanoterm auth logout​

ws​

nanoterm ws create​

nanoterm ws list​

nanoterm ws ports <id>​

nanoterm ws stop <id> / start <id>​

nanoterm ws rm <id>​

exec​

exec-wait​

shell​

attach​

files​

nanoterm files cp <src> <dst>​

nanoterm files write <id> <path>​

nanoterm files tail <id> <path>​

secrets​

nanoterm secrets list​

nanoterm secrets set <name>​

nanoterm secrets rm <name>​

nanoterm secrets auth-claude​

nanoterm secrets auth-codex​

nanoterm secrets auth-github​

nanoterm secrets run -- <cmd>​

nanoterm secrets status​

snapshot​

proxy​

その他のコマンドグループ​

自動アップデート通知​