# CLI

手元で使う CLI は `aikagi` という実行ファイル 1 つです。常駐するプロセスはありません。

## インストール

Linux では、次のコマンドを実行します。`~/.local/bin` にインストールされ、管理者権限は不要です。

```sh
curl -fsSL https://aikagi.dev/install.sh | sh
```

インストール先を変える場合は、`AIKAGI_INSTALL_DIR` を指定してください。

Windows x64 では、PowerShell で次の 3 行を実行します。WSL は不要です。ユーザーの PATH は自動で更新されます。

```sh
$installer = Join-Path $env:TEMP 'aikagi-install.ps1'
Invoke-WebRequest https://aikagi.dev/install.ps1 -OutFile $installer
& $installer
```

インストール後は、新しい PowerShell 7 のセッションで `aikagi login`、`aikagi init`、`aikagi hook install --shell pwsh` を実行します。別のプロジェクトのディレクトリに移動した後は、`__aikagi_chpwd` を実行すると、対象のワークスペース・プロジェクト・環境を読み直します。

## 更新する

```sh
aikagi upgrade
```

aikagi を最新のバージョンに入れ替えます。新しいバージョンがあるかを CI で確認するだけなら、`aikagi upgrade --check` を使います（新しいバージョンがあるときだけ終了コード 10 を返します）。

### 自動更新

```sh
aikagi upgrade --auto status
aikagi upgrade --auto off
```

自動更新は既定で有効です。1 日 1 回、バックグラウンドで新しいバージョンを確認して入れ替え、次に実行したコマンドで 1 行だけ知らせます。コマンドの実行を待たせることはありません。古いバージョンに戻すことはしません。

更新は、必ずこの端末から取得しに行きます。aikagi のサーバからあなたの PC にプログラムを送り込む仕組みはありません。

管理対象の端末や CI では、`AIKAGI_AUTO_UPDATE=0` で自動更新を止められます（この端末での設定より優先されます）。環境変数 `CI` が設定されている環境では、自動更新は既定で無効です（明示的に有効にした場合だけ動きます）。`AIKAGI_NO_UPDATE_CHECK=1` を設定すると、新しいバージョンの確認そのものを止めます。

自動更新は 0.3.2 からの機能です。それより前のバージョンを使っている場合は、1 回だけ `aikagi upgrade` を実行してください。値を読むコマンドを実行したときに、そのことが 1 行で表示されます。以後は手動で更新する必要はありません。

### 署名の検証

配布物には署名が付いています。`aikagi upgrade` と自動更新は、ダウンロードしたアーカイブのチェックサムと、aikagi に埋め込んだ公開鍵による署名の両方を検証できたときだけ入れ替えます。どちらかが一致しなければ、現在の aikagi をそのまま残します。

インストーラも、`minisign` がインストールされていれば署名を検証します。`minisign` が無い場合はチェックサムだけを検証し、そのことを 1 行表示します。

## 最初に実行するコマンド

```sh
aikagi login
aikagi init
aikagi hook install
```

`login` はブラウザを開き、この端末のログインを承認します（[端末](https://aikagi.dev/guide/devices.md)）。画面の無いサーバでは、コード入力の方式に切り替わります（[サーバから使う](https://aikagi.dev/guide/server.md)）。`init` は作業中のリポジトリをプロジェクトに紐付け、`.aikagi.toml` を作成します。`hook install` は、`claude` や `codex` が aikagi を経由して起動するように設定し、そのリポジトリで読めるキーの値を環境変数として渡します。

`init` は対話形式で進みます。リポジトリの名前からワークスペースとプロジェクトを推測して提案するので、そのままでよければ Enter を押すだけです。プロジェクトが無ければ、その場で作成できます。自分用のワークスペースに紐付けるときは、ワークスペースの名前だけを書きます。

## AI ツール向けの skill

`login` と `hook install` は、AI のコーディングエージェントに aikagi の使い方を伝える skill もインストールします。skill があると、AI は値が必要な場面で `aikagi run -- コマンド` を使い、値を会話にもファイルにも書かずに作業を進めます。

- **Claude Code**: `~/.claude/skills/secrets/`。`CLAUDE_CONFIG_DIR` を設定している場合は、その下の `skills/secrets/` です。
- **Codex など**: `~/.agents/skills/secrets/`。Agent Skills の形式に対応したエージェントが共通で読む場所です。

aikagi を更新すると、次の実行時に skill も更新されます。手で編集した skill は上書きしません。

skill の名前は `secrets` です。同じ名前の skill がすでにある場合は、その skill はそのまま残し、`aikagi-secrets` という名前でインストールします。以前の版が `aikagi` という名前でインストールした skill は、`secrets` に置き換えます。インストール・更新・置き換えをした場所は、実行時にすべて表示します。

```sh
aikagi skills status
aikagi skills off
aikagi skills on
```

`status` はエージェントごとのインストール状況を表示します。`off` はインストール済みの skill を削除し、以後インストールしないようにします。その回だけインストールしない場合は、`login` や `hook install` に `--no-skills` を付けます。

skill はリポジトリにも置けます。`init` の実行中に「このリポジトリにも置くか」を聞かれます。置いてコミットすると、チームの AI ツールも同じ使い方をします。後から置く場合は `aikagi skills on --repo` を実行します。

## キーを操作する

- **`aikagi ls [フォルダ]`**: キーの名前を一覧で表示します。値は表示しません。`--recursive` を付けると、下のフォルダまで表示します。
- **`aikagi get 名前`**: 値を 1 つだけ標準出力に出力します。
- **`aikagi set 名前`**: 値を保存します。値は標準入力から渡してください。`--comment` でコメントを付けられます。
- **`aikagi set 名前 --mine`**: 共有の値より優先される[自分だけの値](https://aikagi.dev/guide/keys.md#mine)を設定します。版を持たないため、`--comment` とは併用できません。
- **`aikagi rm 名前`**: キーを削除します。履歴も一緒に削除されます。
- **`aikagi rm 名前 --mine`**: 自分だけの値を解除します。共有の値は残ります。
- **`aikagi history 名前`**: 版の一覧を表示します。値は表示しません。
- **`aikagi rollback 名前 --version N`**: 指定した版の値で、新しい版を作成します。
- **`aikagi export`**: 現在の対象（プロジェクトと環境）のキーをまとめて出力します。`--format json` も指定できます。
- **`aikagi import FILE`**: `.env` 形式のファイルをまとめて読み込みます。詳しくは[他のサービスからの移行](https://aikagi.dev/guide/import.md)を参照してください。
- **`aikagi run -- コマンド`**: 読めるキーの値を環境変数に入れて、そのコマンドを 1 回実行します。

値を引数に書くと、シェルの履歴に残ります。`set` には標準入力から値を渡してください。

```sh
printf %s "$VALUE" | aikagi set openai/api_key
```

## AI に値を渡さず登録する

この操作には CLI 0.4.3 以降が必要です。`aikagi --version` で版を確認してください。0.4.2 では Web アプリから登録してください。

AI が認証情報の入力を扱えない場合は、本人が入力するフォームを開けます。保存先とキーの名前を指定するため、画面で探し直す必要はありません。

```sh
aikagi set openai/api_key -w acme -p web-app -e development --web --no-browser --json
```

返された `setup_url` を本人のブラウザで開き、ワークスペース・プロジェクト・環境・キーを確認してから値を入力します。URL に値は含まれません。フォームは既存の値を取得せず、置き換える場合は明示的に選択します。

`--no-browser` を省略すると、その端末のブラウザを開きます。サーバや AI の実行環境では `--no-browser` を付け、URL を本人に渡してください。

このコマンドは `written: false` と `status: awaiting_user` を返します。ブラウザを開いただけでは保存済みになりません。本人の保存が完了した後、`aikagi ls -r` や `aikagi history openai/api_key` で名前や版を確認してください。確認のために値を読み出す必要はありません。

skill は利用者が依頼した登録を支援しますが、AI 側の安全確認や入力方法の制約を変更しません。新しい継続アクセスの許可が必要な場合は、その確認を別途行います。このフォームは共有の値用で、`--mine`、`--comment`、値の引数とは併用できません。

## 対象のワークスペース・プロジェクト・環境

コマンドの対象になるワークスペース・プロジェクト・環境は、オプションの指定、環境変数、`.aikagi.toml` の順に優先して決まります。次のオプションは、どのコマンドにも付けられます。

- **`-w` / `--workspace`**: ワークスペース。
- **`-p` / `--project`**: プロジェクト。
- **`-e` / `--env`**: 環境。

現在の対象は `aikagi status` で確認できます。対象を決める情報が何も無い場合は、足りない項目を質問します。

## .aikagi.toml

リポジトリのルートに置く設定ファイルです。**値は含みません。**そのままリポジトリにコミットして、チームで共有してください。

```sh
workspace   = "acme"
project     = "web-app"
environment = "development"

[branches]
main    = "production"
release = "staging"

[commands.claude]
[commands.codex]
```

`[branches]` を書くと、git のブランチに応じて環境が決まります。一致するブランチが無い場合は `environment` の値を使います。`[commands.…]` に書いたコマンドは、起動時にキーの値を受け取ります。

**認証情報は書きません。**誰として値を取得するかは、その端末のログイン（[端末](https://aikagi.dev/guide/devices.md)）か、GitHub Actions の OIDC token（[CI・デプロイで使う](https://aikagi.dev/guide/ci.md)）で決まります。

## チームを管理する

```sh
aikagi workspace create acme
aikagi project create acme/web-app
aikagi env add qa -w acme -p web-app
aikagi share acme/web-app teammate@example.com --role editor
aikagi audit --since 24h
```

## 共通のオプション

- **`--json`**: JSON で出力します。スクリプトから呼ぶときに使います。
- **`-q` / `--quiet`**: 補足の出力を止めます。
- **`-y` / `--yes`**: 確認に自動で「はい」と答えます。対話できない環境で削除する場合は必須です。

失敗の種類は終了コードで判別できます。

- **0**: 正常終了
- **1**: その他の失敗
- **2**: 指定内容の誤り（引数・オプション・キーの名前など）
- **3**: 認証の失敗
- **4**: 権限が無い
- **5**: 対象が見つからない
- **6**: サーバに接続できない

## 状態を診断する

```sh
aikagi doctor
```

認証情報の取得元、PATH の順序、シェルの設定、skill、サーバに接続できるかを順に確認し、問題があれば直し方を 1 行ずつ表示します。サーバに接続せずに確認する場合は `--offline` を付けてください。

---

出典: https://aikagi.dev/guide/cli/