メインコンテンツへスキップ

arc afs

arc afs は、AFS ファイルシステム操作のためのコマンドグループです：パスの一覧表示・読み取り・書き込み・削除・検索、action の実行、マウントの管理です。

arc afs は、AFS ファイルシステム操作のためのコマンドグループです。すべてのサブコマンドは、あなたのマシン上の生のファイルシステムパスではなく、/src や /data のようなマウントされた場所である AFS パスに対して動作します。

arc 2.0.0-beta.50（commit a99fb2c37、main、2026-09-11）に対して取得したものです。dump をコピーする前に arc --version を実行してください。コマンド面を固定するのは commit です。

bash
arc afs <subcommand> [options]

完全なサブコマンド一覧を見るには arc afs --help を実行してください。すべてのサブコマンドは、概要 に記載されているグローバルな --json、--view <default|llm|human|json>、--instance / -i、--home <dir> フラグも受け付けます。--yaml は削除されました（実装されたことは一度もない）；--json または --view json を使ってください。

認識できないフラグは、今では拒否されます（Unknown argument: <name>、exit 5）。黙って無視されることはありません —— 例えば arc afs ls --bogus-flag foo は、--bogus-flag を捨てて実行されるのではなく失敗します。

このコマンドはどのインスタンスと話すか

arc afs は、実行対象となる稼働中のインスタンスを必要とします。フラグなしの場合、default のバックグラウンドインスタンス（裸の arc service start で起動したもの）に接続します。何も動いていない場合、arc afs のすべてのサブコマンドは、使い捨ての ad-hoc AFS へ黙ってフォールバックするのではなく、非ゼロで終了します:

bash
$ arc afs ls /
ERROR: No AFS daemon is running for instance "default".
Start it with:  arc service start
Or use --standalone for ad-hoc mode (no runtime state)
  • --instance <name> / -i：グローバル。デフォルトのインスタンスではなく、名前付きインスタンスに接続する（arc service list を参照）。省略すると default
  • --home <dir>：グローバル。インスタンスのルート。arc service start（作成）、--standalone（ad-hoc）、arc did init で使われる。どのインスタンスにするかを選ぶには --instance を使う。両方を渡し、それらが異なるインスタンスを指す場合、コマンドは失敗する
  • --standalone：ad-hoc モードを強制する —— 稼働中のデーモンに接続する代わりに、現在のディレクトリのローカルな .afs-config/config.toml から直接 AFS をロードする。ランタイムの状態はない（他で追加したマウントやライブの subscription などは見えない）；リマインダーとして stderr に [standalone] not attached to any instance の行を表示する
bash
arc service start --instance docs-demo --home ~/docs-demo   # 名前付きインスタンスを一度起動する
arc afs ls / --instance docs-demo                 # every later afs call names it explicitly

読み取りと一覧表示

arc afs ls

ディレクトリの内容を一覧表示します。

使用法

bash
arc afs ls [path] [options]
  • [path]（省略可、デフォルト /）：一覧表示する AFS パス
  • --depth <n>：一覧表示する最大の深さ（デフォルト 1）
  • -l：詳細な一覧形式、種類とサイズを表示する
  • -R：再帰的に一覧表示する
  • --limit <n>：返すエントリ数の上限
  • --max-children <n>：ディレクトリごとの子要素数の上限
  • --pattern <glob>：glob パターンでエントリを絞り込む

arc afs list という別名でも使えます。

-R と明示的な --depth は排他的です —— -R は常に深さ 10 で一覧表示するため、--depth と組み合わせると、どちらが優先されるのかが曖昧になります:

bash
$ arc afs ls /demo -R --depth 2
ERROR: ls: --depth conflicts with -R (recursive always lists at depth 10) — choose one: drop --depth to use -R's depth of 10, or drop -R and pass --depth explicitly

存在しないパスは exit 1 になります（空リストで 0 になることも、5 になることもありません）:

bash
$ arc afs ls /demo/does-not-exist
ERROR: No data found for path: /demo/does-not-exist

例：再帰的、詳細な一覧表示

bash
arc afs ls /demo -l -R
└── 📁 demo
    ├── 📄 notes.txt (fs:file)  15B
    └── 📁 reports (fs:directory)
        └── 📄 q1.txt (fs:file)  15B

arc afs read

ファイルの内容を読み取ります。

使用法

bash
arc afs read [path] [options]
  • [path]（位置引数、または --path <path>、いずれか一方が必須）：読み取るパス
  • --start-line <n>：開始行、1 始まり、境界を含む
  • --end-line <n>：終了行、1 始まり、境界を含む；-1 はファイルの終端

arc afs cat という別名でも使えます。

例

bash
$ arc afs read /demo/notes.txt
Hello from AFS

存在しないパスは exit 1 になります:

bash
$ arc afs read /demo/does-not-exist.txt
ERROR: No data found for path: /demo/does-not-exist.txt

arc afs stat

ファイルまたはディレクトリの情報を取得します。

使用法

bash
arc afs stat [path]
  • [path]（位置引数、または --path <path>、いずれか一方が必須）：検査するパス

例

bash
$ arc afs stat /demo/notes.txt
PATH=/demo/notes.txt
KIND=fs:file
SIZE=15
MODIFIED=2026-08-01T04:00:51.508Z

存在しないパスは exit 1 になり、arc afs read と同じメッセージ・終了コードです:

bash
$ arc afs stat /demo/does-not-exist.txt
ERROR: No data found for path: /demo/does-not-exist.txt

arc afs search

AFS パス内でコンテンツを検索します。

使用法

bash
arc afs search [path] [query]
  • [path]（位置引数、または --path <path>、いずれか一方が必須）：検索対象のパス
  • [query]（位置引数、または --query <text>、いずれか一方が必須）：検索クエリ

arc afs grep という別名でも使えます。find の別名ではありません —— find は削除されました（それは名前ではなくコンテンツを検索するものだったため；名前でエントリを絞り込みたい場合は代わりに arc afs ls --pattern を使ってください）。

例

bash
$ arc afs search /demo revenue
/demo/reports/q1.txt

arc afs explain

AFS の概念やパスを説明します。引数なしの場合は、一般的な概要（mount / path / uri の概念）を表示します。topic または実際の AFS パスを指定した場合は、それについて具体的に説明します。

使用法

bash
arc afs explain [topic]
  • [topic]：概念名（mount、path、uri）または /src のような AFS パス。位置引数の代わりに --topic <value> として渡すこともできる

例

bash
$ arc afs explain
AFS Overview
============

AFS (Agentic File System) is a virtual filesystem that unifies different data sources into a single namespace.

Core Concepts:
- mount: Mount a data source to a virtual path
- path: Virtual path, e.g., /src, /data
- uri: Data source address, e.g., fs://, git://, sqlite://

Data Flow:
  User Path -> AFS -> /{mount} -> Provider -> Actual Data

Examples:
  $ arc afs mount add /src fs:///path/to/source
  $ arc afs ls /src
  $ arc afs read /src/file.txt

arc afs subscribe

あるパス以下の AFS イベントを subscribe します。Ctrl-C を押すまで、1 行につき 1 つの JSON イベントを表示します。別のプロセス（ビルドツール、別の arc afs write、稼働中の blocklet）によるマウントへの変更を監視するのに便利です。

使用法

bash
arc afs subscribe [path] [options]
  • [path]（省略可、デフォルト /）：監視するパスのプレフィックス、例：/demo や /dev/code-agents。--path <value> として渡すこともできる
  • --type <pattern>：イベントタイプのフィルタ、例：afs:write、afs:*（デフォルト afs:write、ワイルドカード可）

例（一方のターミナルでこれを実行し、もう一方で arc afs write /demo/hello.txt ... を実行する）

bash
$ arc afs subscribe /demo
Subscribed to /demo (type=afs:write) — Ctrl-C to stop
{"type":"afs:write","path":"/demo/hello.txt","source":"fs","timestamp":1787870798884}

書き込みと削除

arc afs write

ファイルにコンテンツを書き込みます。

使用法

bash
arc afs write [path] [content] [options]
  • [path]（位置引数、または --path <path>、いずれか一方が必須）：書き込むパス
  • --content <text>：書き込むコンテンツ
  • --mode <mode>：replace（デフォルト）、append、prepend、patch、create、update のいずれか
  • --patch <json>：patch 操作の JSON 配列、--mode patch と併用する
  • --meta <key=value>：メタデータのフィールドを設定する、繰り返し可能
  • --if-match <version>：以前の stat/read/write から得た楽観的並行性制御のトークン。現在のバージョンと異なる場合、書き込みは AFS_CONFLICT で拒否される；これをサポートしない provider はこのフラグを無視する（最後に書いたものが勝つ）

例：書き込み、その後追記

bash
$ arc afs write /demo/draft.txt --content 'first draft'
OK /demo/draft.txt

$ arc afs write /demo/draft.txt --content ' plus more' --mode append
OK /demo/draft.txt

$ arc afs read /demo/draft.txt
first draft plus more

arc afs delete

ファイルまたはディレクトリを削除します。

使用法

bash
arc afs delete [path] [options]
  • [path]（位置引数、または --path <path>、いずれか一方が必須）：削除するパス
  • -r, --recursive：ディレクトリを再帰的に削除する（デフォルト false）
  • --dry-run：実際には削除せず、削除されるはずのものを表示する
  • --yes：TTY の確認プロンプトをスキップする（このプロンプトは stdin が本物の TTY のときにのみ表示される；非対話的な arc afs delete（スクリプト、CI、本ドキュメント自身の例）は、どちらにせよそれで止まることはない）

arc afs rm という別名でも使えます。

例：プレビュー、その後削除

bash
$ arc afs delete /demo/draft.txt --dry-run
Would delete /demo/draft.txt (dry-run)

$ arc afs stat /demo/draft.txt
PATH=/demo/draft.txt
KIND=fs:file
SIZE=21

$ arc afs delete /demo/draft.txt --yes
OK /demo/draft.txt

action を実行する

arc afs exec

指定したパスで provider が公開している action を実行します。例えば、単純なファイルの読み書きではない、provider が独自に定義した操作です。

使用法

bash
arc afs exec <executable_path> [options]
  • executable_path（必須）：実行する action のパス
  • --args <json>：JSON 形式の引数、例：--args '{"key": "value"}'

すべてのマウントが action を公開しているわけではありません。稼働中のインスタンスに接続された素の fs:// マウントに対して action パスを呼び出すと、現在は具体的なエラーではなく汎用的なサーバーエラーになります —— デーモンの HTTP 層は、このケースでは AFS の下層のエラーテキストを伝播しません:

bash
$ arc afs exec /demo/.actions/foo
ERROR: Internal server error

--standalone モード（デーモンが介在しない）では、同じ呼び出しが代わりに具体的なメッセージを受け取ります:

bash
$ arc afs exec /demo/.actions/foo --standalone
ERROR: No actions available for path: /.actions/foo

マウント管理

arc afs mount は、何がどこにマウントされているかを管理する、独立したサブコマンドグループです。

bash
arc afs mount <subcommand> [options]

arc afs mount add は、現在のディレクトリから上に向かって探して見つかった .afs-config/config.toml に書き込みます —— どの --instance/--home インスタンスにも書き込みません。--home は直接拒否されます（exit 5）。そのフラグは変更がインスタンスのデーモンに届くことを暗示しますが、実際には決して届きません。--instance / -i はグローバルなインスタンス選択子です：そのインスタンスが動いていなければ、コマンドは mount add の前に失敗します。--home を外し、正しいディレクトリから実行してください。稼働中のインスタンスがマウントしているものを変更するには：arc afs mount add を実行する前に、そのインスタンスの home ディレクトリ（arc service start --home に渡したもの）に cd してください。そうすれば、再起動なしでそのインスタンスに即座に反映されます。（これが AFS runtime boundaries ページにある「mount add は自動的に acceptance path になるわけではない」という注意事項の裏にある仕組みです —— 間違ったディレクトリから mount add を実行すると、そのマウントは mount list には現れるのに ls には現れない、という状態になります。）

bash
$ arc afs mount add /demo fs:///path/to/a/local/directory --instance docs-demo
ERROR: no instance named "docs-demo". `arc service list` shows 0

$ arc afs mount add /demo fs:///path/to/a/local/directory --home /Users/you
ERROR: --home is not supported by `arc afs mount add`. `arc afs mount` only reads and writes the `.afs-config/config.toml` found by walking up from the current directory; it never reaches an instance's daemon, so the selected instance would silently not see the change. Drop the flag to edit the cwd config, or mount into a running instance at runtime with `arc attach --to <daemon-url> --namespace <ns> --source <dir>`.
bash
cd ~/docs-demo                                    # このインスタンスの --home ディレクトリ
arc afs mount add /demo fs:///path/to/a/local/directory
arc afs ls /demo --instance docs-demo               # visible right away

arc afs mount add

マウントを追加します。

使用法

bash
arc afs mount add <path> <uri> [options]
  • path（必須）：マウントパス、例：/src
  • uri（必須）：provider の URI、例：fs://./src
  • --namespace <name>：マウントの namespace
  • --description <text>：マウントの説明
  • --sensitive-args <names>：センシティブな資格情報として扱うフィールド名
  • -s, --set <key=value>：資格情報を直接設定する、繰り返し可能、対話的なプロンプトを回避する
  • --terminal：ブラウザの代わりに terminal readline で資格情報を収集する
  • -f, --force：キャッシュされた値を無視して、資格情報の再収集を強制する

例

bash
$ arc afs mount add /demo fs:///path/to/a/local/directory
Mounted fs:///path/to/a/local/directory at /demo

arc afs mount list

すべてのマウントを一覧表示します。

使用法

bash
arc afs mount list [options]

arc afs mount ls という別名でも使えます。--namespace フィルタはありません —— cwd の .afs-config/config.toml は 1 つのテーブルであり、絞り込める namespace ごとの分割はないため、--namespace を渡すと拒否されます:

bash
$ arc afs mount list --namespace anything
ERROR: --namespace is not supported by `arc afs mount list`. `arc afs mount` reads and writes the cwd `.afs-config/config.toml` as one table; there is no per-namespace slice. Drop --namespace.

例（1 件だけ表示；実際の一覧には、あなたが追加したすべてのマウントが含まれます）

bash
$ arc afs mount list
/demo -> fs:///path/to/a/local/directory

arc afs mount remove

パスをアンマウントします。

使用法

bash
arc afs mount remove <path> [options]
  • path（必須、位置引数のみ）：削除するマウントパス。--help には [required] と表示された --path オプションも一覧に載っていますが、これを位置引数の代わりにフラグとして渡しても要件は満たされません —— それでも Not enough non-option arguments: got 0, need at least 1 で失敗します。パスは必ず位置引数として渡してください
  • --namespace <name>：サポートされていません —— arc afs mount は cwd の .afs-config/config.toml を、namespace ごとの分割のない 1 つのテーブルとして扱うため、remove --namespace foo は拒否されます（ERROR: --namespace is not supported by 'arc afs mount remove'）、mount list と同様です

arc afs mount rm という別名でも使えます。

例

bash
$ arc afs mount remove /demo
Unmounted /demo

--help が必須オプションとして一覧に載せているにもかかわらず、パスを位置引数の代わりに --path として渡してもうまくいきません:

bash
$ arc afs mount remove --path /demo
ERROR: Not enough non-option arguments: got 0, need at least 1

arc afs mount validate

現在のマウント設定を検証します。

使用法

bash
arc afs mount validate

例

bash
$ arc afs mount validate
Configuration is valid

出力に関する注記

afs コマンドが稼働中のインスタンス（デフォルト）と話す場合、stderr にはまったく何も書き込みません：stdout の結果が出力の全体です。起動ログはデーモンに属するものであり、あなたのシェルに属するものではありません。

--standalone は例外です。そこではコマンドが自分自身のプロセス内で AFS を起動し、その起動ログがあなたの端末に流れるからです。3 行は不変です —— ad-hoc モードであることを示す行、どの .afs-config/config.toml ファイルを読んだかを回答する行、そして AFS_DID_SPACE_SCOPE_SECRET が未設定のときはいつでも、DID Space の scope の脱識別化が off であり、ディレクトリ名が平文で保存されていることを報告する node:boot からの warn 記録です:

text
[standalone] not attached to any instance — ad-hoc mode (no runtime state)
[standalone] config: /path/to/.afs-config/config.toml
{"ts":"…","level":"warn","service":"arc-node","ns":"node:boot","message":"[afs-loader] AFS_DID_SPACE_SCOPE_SECRET unset — DID Space scope de-identification is OFF (plaintext directories). Set the secret to enable; set AFS_DID_SPACE_REQUIRE_DEID=true to enforce."}

secret を設定すると、3 行目はなくなります；AFS_DID_SPACE_REQUIRE_DEID=true を設定すると、代わりにそれが未設定であることをエラーにします。stderr にこれ以上出てくるものは、あなた自身のマシンについて node:boot が報告しているもの —— 確立できなかったマウントや、スケジューラ自身の起動による [code-agents] recover ok: ... の行など —— なので、総行数はホストによって異なります。行数を数えるのではなく、上記の 3 行を見分けてください。それらのいずれも、コマンドの結果の一部ではなく、上の例からはすべて省略されています。