agent-fs

agent-fs CLI

agent-fs は、完全なバージョン管理、全文検索（FTS5）、セマンティック検索を備えた、エージェントファーストのファイルシステムです。JSON を出力する CLI を提供しており、エージェントのワークフローに最適です。ファイルは組織内のドライブに整理されます。

ストレージバックエンド

agent-fs は、プラグイン可能なストレージバックエンドにファイルのバイトデータを保存します。永続的な価値であるバージョン履歴、コメント、検索は SQLite に保存され、すべてのバックエンドで同じように機能します。

バックエンド	セットアップ	バージョン管理の階層	signed-url
S3 / MinIO（デフォルト）	agent-fs onboard -y（ローカル MinIO、Docker が必要）、または任意の S3 互換ストア（AWS、R2、Tigris など）用の --s3-* フラグ	フル — S3 オブジェクトのバージョン管理による revert と過去の diff	実際の署名付き URL（公開、期限付き）
ローカルファイルシステム	agent-fs onboard --filesystem（Docker も S3 も不要）	フル — ディスク上のコンテンツアドレス方式の blob による revert と過去の diff	認証済みのアプリ内リンクにフォールバックします（サインインが必要で、期限切れになりません）

どちらのバックエンドもフル階層であり、revert や過去の diff を含むすべての操作が機能します。将来のバックエンドは基本階層（オブジェクトのバージョン管理なし）になる可能性があります。その場合、revert と過去の diff は利用できず、生のストレージエラーではなく UNSUPPORTED_OPERATION エラー（HTTP 422）を適切に返します。現在のコンテンツ、一覧表示、コメント、検索は引き続き機能します。ドライブがどのバックエンドを使用しているか不明な場合は、バージョン管理に依存する前にバックエンドの機能を確認してください。

クイックスタート

# 1. Set up (local MinIO — requires Docker)
agent-fs onboard -y

#    ...or with no Docker/S3 at all — store bytes on the local filesystem:
agent-fs onboard --filesystem            # uses ~/.agent-fs/storage
agent-fs onboard --filesystem --storage-root /data/agent-fs   # custom dir

# 2. Optionally start the daemon (CLI auto-detects and works without it)
agent-fs daemon start

# 3. Start using it
echo "hello world" | agent-fs write docs/readme.txt -m "initial version"
agent-fs cat docs/readme.txt

カスタム S3（AWS、R2 など）を使う場合は、フラグを指定します：agent-fs onboard --s3-endpoint <url> --s3-bucket <name> --s3-access-key <key> --s3-secret-key <key>。

ローカルファイルシステムのバックエンド（--filesystem、または同等の --storage local）には、Docker も S3 も必要ありません。バイトデータは --storage-root（デフォルトは ~/.agent-fs/storage）の下に保存され、各バージョンはコンテンツアドレス方式で保存されるため、S3 と同じように revert と過去の diff が機能します。

just-bash アダプター

just-bash 環境で agent-fs を fs 実装として使って読み書きする必要がある場合は、@desplega.ai/agent-fs-just-bash を使用します。

import { Bash } from "just-bash";
import { AgentFsFileSystem } from "@desplega.ai/agent-fs-just-bash";

const fs = new AgentFsFileSystem({
  baseUrl: process.env.AGENT_FS_API_URL,
  apiKey: process.env.AGENT_FS_API_KEY,
  orgId: "org_...",
  driveId: "drive_...",
});

const bash = new Bash({ fs, cwd: "/" });

このアダプターは、バイトセーフな読み書きに /raw を、一覧表示とメタデータに /ops を使用します。空のディレクトリは非表示の .agent-fs-dir マーカーで表現されます。シンボリックリンクには対応しておらず、EPERM がスローされます。

基本的なパターン

1. 機械処理用の出力には JSON を使用する — CLI 出力を解析するときは --json を指定してください（-o を指定しない download は標準出力に生のバイトデータを書き込みます。また、daemon status と auth register は人間が読めるテキストを出力します）。

2. 自動検出 — CLI はデーモンが実行中かどうかを自動的に検出します。実行中の場合、コマンドは HTTP 経由で送信され、そうでない場合は組み込みモードを直接使用します。ユーザーによる操作は不要です。

3. デフォルトの組織／ドライブの解決 — --org／--drive フラグがない場合、CLI は次の順に解決します：フラグ自体、ローカル設定（org switch <id>／drive switch <id>。マシンごとに保持）、AGENT_FS_DEFAULT_ORG_ID／AGENT_FS_DEFAULT_DRIVE_ID 環境変数（デプロイレベルのヒント。例：エージェントスウォームのワーカーコンテナが書き込み先として割り当てられた共有組織）、GET /me から取得するアカウント自身のデフォルト組織／ドライブ（変更されていない限り、自動作成された個人用組織）。書き込み先が想定外の場合は、agent-fs org current／agent-fs drive current の source フィールドを確認してください。フラグを指定しない書き込みは、先行する設定のいずれかが指定されていない限り、常に個人用の組織／ドライブに書き込まれます。

4. 標準入力とファイルのアップロード — write は標準入力または --file から生のバイトデータを、--content からテキストを受け取ります。append は標準入力または --content からテキストを受け取ります：

   # Preferred for multi-line text
   echo "content here" | agent-fs write path/to/file.txt
   
   # Inline for short content
   agent-fs write path/to/file.txt --content "short text"
   
   # Binary-safe upload
   agent-fs write assets/screenshot.png --file ./screenshot.png
   

5. パス：スラッシュを使用してください。先頭のスラッシュは省略できます。Agent FS は /docs/notes/meeting.md のような正規形でパスを返し、保存します。

6. バージョンメッセージ — 省略可能ですが、監査可能性を高めるため推奨します：

   agent-fs write docs/spec.md --content "..." -m "added API section"
   

7. 楽観的同時実行制御 — write で --expected-version を使用し、競合を防止します：

   agent-fs write config.json --content '{}' --expected-version 3
   # Fails if file is not at version 3
   

コマンドのクイックリファレンス

ファイル操作

コマンド	使用方法	説明
write	agent-fs write <path> [--content <text>] [--file <local-path>] [-m <msg>] [--expected-version <n>]	テキストまたはバイナリデータを書き込みます
cat	agent-fs cat <path> [--offset <n>] [--limit <n>] [--raw]	テキストファイルの内容を読み取ります
edit	agent-fs edit <path> --old <text> --new <text> [-m <msg>]	ファイル内を検索して置換します
append	agent-fs append <path> [--content <text>] [-m <msg>]	ファイルに追記します（stdin または --content）
tail	agent-fs tail <path> [--lines <n>]	末尾の N 行を表示します（デフォルト：20）
ls	agent-fs ls [path]	ディレクトリの内容を一覧表示します（デフォルトは /）
stat	agent-fs stat <path>	ファイルのメタデータを表示します（サイズ、バージョン、タイムスタンプ、埋め込みの状態：pending、indexed、failed、skipped のいずれか、現在のバイト列の etag：内容が変更されたかどうかを判定するには等しいか比較します）
reveal	agent-fs reveal <path>	1 回の呼び出しで、ファイルをツリー表示するために必要な情報をすべて取得します。すべての親ディレクトリの ls 一覧（ルートから順に listings: [{ path, entries }] として表示）と、ファイルの stat が含まれます。権限は ls と同じです。ファイルが存在しない場合は NOT_FOUND を返します。通常の読み取りには ls／stat を優先してください。
tree	agent-fs tree [path] [--depth <n>]	ディレクトリを再帰的に一覧表示します
glob	agent-fs glob <pattern> [--path <prefix>]	すべてのストレージページを対象に、パターン（*.md、**/*.md）でファイルを検索します
rm	agent-fs rm <path>	ファイルを削除します
mv	agent-fs mv <from> <to> [-m <msg>]	ファイルを移動または名前変更します
cp	agent-fs cp <from> <to>	ファイルをコピーします
signed-url	agent-fs signed-url <path> [--expires-in <seconds>] [--inline]	ダウンロード URL を生成します。S3／MinIO では署名付き URL（デフォルトは 24 時間、最長 7 日間、kind: "presigned"）です。local-FS では認証済みアプリ内リンク（kind: "app"、サインインが必要、期限なし）です。デフォルトでは URL はファイルをダウンロードします。--inline を指定すると、ブラウザーでファイルを表示します（PDF、画像）。
share-create	agent-fs share-create <path> [--expires-in <seconds>] [--max-views <n>] [--one-off]	ファイルまたはフォルダーの公開リンクを作成します。ファイルの場合、API ホスト上に /share/<token> ページが作成され、読み取り専用のプレビュー（Markdown、テキスト／コード、画像、PDF、音声、動画、サンドボックス内でレンダリングされる HTML）とダウンロードボタンが表示されます。フォルダーの場合、/site/<token>/ に HTML サイトが作成されます（kind: "site"、閲覧回数の制限なし）。デフォルトは 24 時間、最長 7 日間です。--one-off（= --max-views 1）を指定すると、ファイルのリンクは 1 回限りになります。{ id, kind, url, sharePath, expiresAt, maxViews } を返します。
share-revoke	agent-fs share-revoke [<id>] [--token <token-or-url>] [--path <path>]	共有リンクをすぐに無効化します。セレクターは 1 つだけ指定します。share-create が返した id、トークン／URL、またはファイル／フォルダーのパス（そのファイル／フォルダーへのすべてのリンク）を指定できます。作成者またはドライブ管理者のみ実行できます。
download	agent-fs download <path> [-o <local-path>]	生のバイト列をダウンロードします
watch	agent-fs watch [--json]	Ctrl+C が押されるまで、アクティブなドライブの変更をストリーミングします。Bearer エンドポイント：GET /orgs/:orgId/drives/:driveId/events は ready、file.changed、comment.changed を送信します。

cat は生のファイルを読み取るコマンドではなく、ページ分割されたビューアーです。--limit を指定しない場合、TTY ではデフォルトで先頭の 200 行を表示しますが、stdout がパイプまたはリダイレクトされている場合はファイル全体を返します（パイプ／リダイレクトは、ほぼ常に「すべて取得する」という意味です）。cat が要求された行数より少ない行しか返さない場合は、truncated: showing N of M lines (use --limit) という注記がstderr に出力されます。stdout には出力されないため、パイプ／リダイレクトの出力が壊れることはありません。デフォルトの表示（--raw を指定せず、TTY を使用）は、読みやすさのため各行の先頭に行番号を付けます。この接頭辞は保存されたバイト列には含まれません。完全かつバイト単位で正確に読み取るには（CSV／JSON として解析する前、または行番号や部分読み込みによってデータが壊れる可能性がある場合に必要です）、agent-fs cat <path> --raw、またはより推奨される方法として agent-fs download <path> -o <file> を使用してください。

バージョン管理

コマンド	使用方法	説明
log	agent-fs log <path> [--limit <n>]	バージョン履歴を表示します
diff	agent-fs diff <path> --v1 <n> --v2 <n>	バージョン間の差分を表示します
revert	agent-fs revert <path> --version <n>	以前のバージョンに戻します

log はすべてのバックエンドで動作します（バージョンのメタデータは SQLite に保存されています）。revert と過去の diff（保存された2つのバージョンの比較）にはフルティアのバックエンドが必要です。S3／MinIO とローカルファイルシステムはいずれも該当します。オブジェクトのバージョニングに対応していないベーシックティアのバックエンドでは、revert は UNSUPPORTED_OPERATION（HTTP 422）を返して正常に失敗し、diff はコンテンツを比較せずに結果を返します。

すべての diff 結果には source が含まれます。値は content（両方のバージョンを比較済み）、summary（比較なし。changes は保存された編集スニペット）、または none（比較なし、サマリーなし。write では何も保存されません）です。バージョンが同一であることを意味するのは、source: "content" かつ changes が空の場合のみです。 それ以外の2つの場合、CLI は stderr に「バージョンは比較されませんでした」という警告を表示します。source が content でない場合に、インプレース編集を確認するには、現在のファイルを cat して編集したテキストを直接確認してください。

Markdown の書き込み時のリンク切れ警告。 write が .md／.mdx ファイルを保存すると、各リンクと画像の参照先を同じドライブ内で確認します。相対パスの参照先は、GitHub やライブビューアーと同様に、ファイルがあるフォルダーを基準に解決されます。たとえば、/reports/a.md 内の img/x.png は /reports/img/x.png を意味し、/img/x.png はドライブのルートを意味します。外部 URL（https:、mailto:、data:）と #anchor リンクは確認対象外です。参照先が見つからない場合、warnings: [{ link, resolvedPath, message }] が返されます。このフィールドは見つからない参照先がある場合にのみ存在し、CLI は stderr に警告を表示します。書き込み自体は成功します。警告は「書き込み時に見つからなかった」ことだけを意味するため、画像を先にアップロードするか、後からアップロードするファイルに関する警告は無視してください。

検索と検出

コマンド	使用方法	説明
grep	agent-fs grep <pattern> <path>	ファイル内容を正規表現で検索します
fts	agent-fs fts <pattern> [--path <prefix>]	アクティブなドライブで FTS5 クエリ構文を使って全文検索します
search	agent-fs search <query> [--limit <n>]	ハイブリッド検索（セマンティック検索＋キーワード検索。一般的なクエリに最適です）
vec-search	agent-fs vec-search <query> [--limit <n>]	アクティブなドライブ内の個別ファイルを対象にセマンティック検索します
recent	agent-fs recent [path] [--since <duration>] [--limit <n>]	最近のアクティビティを表示します（例：--since 24h）
reindex	agent-fs reindex [path]	埋め込みの作成に失敗したファイルや埋め込みがないファイルを再インデックスします。indexed と skipped のファイルはスキップします

使い分け：

• grep — 正確なパターンとパスが分かっている場合（正規表現）
• fts — すべてのファイルを対象にキーワード検索する場合（高速、FTS5 ベース）
• search — キーワードと意味を組み合わせた汎用検索（デフォルトとして推奨）
• vec-search — 概念的な一致のみを求める場合の純粋なセマンティック検索 検索ではアクティブな組織とドライブを使用します。org current と drive current を確認するか、--org と --drive フラグを明示的に指定してください。 glob、ls、tree は、S3 のすべてのリスティングページを読み込みます。1,000 個を超えるオブジェクトがあるドライブも検索できます。 search と vec-search は、アクティブなドライブ内でセマンティック検索の候補を選び、ファイル数を上限にカウントします。 PDF のテキストも検索できます。PDF のテキストヒットには、search と vec-search の結果に page が含まれます。 EmbeddingGemma 2 を使用すると、セマンティック検索では PNG、JPEG、WebP、GIF、および最初の 3 ページ分の PDF 画像も見つかります。 セマンティック検索の一致結果には、kind: "text" または kind: "image" が含まれます。 画像の一致結果には [image] スニペットが使用されます。PDF ページ画像には [PDF page N] スニペットが使用され、page が含まれます。 検索結果は、引き続きファイルごとに 1 件です。最も一致度の高いセマンティックチャンクによって、kind と page が決まります。 ハイブリッド検索では、コサイン類似度が 0.69 以上で、かつ FTS でファイルが見つからない場合に限り、画像のベクトル寄与を 2 倍にします。 類似度がこれより低い場合、ベクトル寄与は 1 つのままです。FTS で一致した場合は、キーワードの寄与も加算されます。 画像のインデックス作成はバックグラウンドで実行されるため、新しい画像が検索結果に表示されるまで時間がかかる場合があります。 ファイルを表示するには agent-fs signed-url <path> --inline を使用します。ダウンロードする場合は --inline を省略してください。 ローカルファイルシステムのバックエンドでは、URL を利用するためにドライブメンバーとして認証されている必要があります。 サーバーで AGENT_FS_EMBEDDING_MAX_BYTES を設定すると、base64 の除去後の UTF-8 バイト数でテキスト埋め込みの上限を指定できます。 正の整数を指定してください。未設定または無効な値の場合、上限は設定されません。 上限を超えたテキストは全文検索では引き続き検索できますが、テキストチャンクとベクトルは失われ、ステータスは skipped になります。 base64 の除去後に 2,000,000 文字を超えるテキストも、バイト数の上限がなくても skipped になります。 上限の対象となるのは、抽出された PDF テキストです。PDF のページオフセットを維持するため、PDF テキストでは base64 が保持されます。画像と PDF ページの埋め込みには変更ありません。 上限を変更した後は再起動してください。起動時に、デーモンは skipped のファイルと新しい上限より大きいインデックス済みファイルをキューに追加します。 上限が設定されている場合、FTS テキストがバイト数の上限を超える、ステータスが従来の NULL のファイルもキューに追加します。 これらの確認では元の FTS バイト数を使うため、base64 を含むファイルが余分にキューに追加されることがあります。

AGENT_FS_EMBEDDING_EXCLUDE_DRIVES を設定すると、カンマ区切りのドライブ ID を指定して、それらのドライブのテキスト、画像、PDF ページの埋め込みを除外できます。 パーサーは ID の前後の空白を除去し、空の項目を無視します。未設定または空の場合、ドライブは除外されません。 除外したドライブでは FTS は維持されますが、ベクトルは失われ、テキストのステータスは skipped になります。画像のステータスは NULL のままです。 変更後は再起動してください。デーモンは、新たに除外されたテキストファイルをキューに追加し、画像のチャンクとベクトルを削除します。 ドライブをリストから外すと、デーモンはそのドライブの skipped のテキストをキューに追加し、画像を再び対象にします。

セマンティック検索の結果には埋め込みが必要です。プロバイダーがない場合、vec-search はヒントを返し、search はキーワードのみの結果であることを示します。 ローカルでセマンティック検索を行うには、EMBEDDING_PROVIDER=local と EMBEDDING_MODEL=embeddinggemma-2 を設定して、EmbeddingGemma 2 を選択します。 モデル設定が空の場合、transformers 4.3.1 をローカルで読み込めれば、新しいインデックスでは EmbeddingGemma 2 が使用されます。読み込めない場合は nomic が使用されます。 既存の nomic インデックスは nomic のままです。EMBEDDING_MODEL=nomic-embed-text-v1.5 を設定すると、明示的に nomic を選択できます。

vec-search のスコアはコサイン類似度です。スコアの尺度はモデルによって異なります。nomic では、一致度の高い結果のスコアは約 0.6 です。絶対的なスコアよりも順位が重要です。各クエリは最も近いファイルを返すため、結果を信頼する前に関連性を確認してください。ハイブリッド search のスコアは順位を 0 から 1 に正規化したもので、1 は、ファイルが一致する可能性のあるすべてのリストで 1 位であることを意味します。3 つすべての検索オペレーションは、クエリにかかったサーバー時間を示す tookMs を返します。埋め込みプロバイダーが使用できないベクトルを返した場合、search と vec-search は EMBEDDING_PROVIDER_ERROR（HTTP 502）で失敗します。プロバイダーの設定を確認してから、もう一度お試しください。

fts は FTS5 の生の構文を受け付けます。句読点を含む語句は、シェルのシングルクォート内で FTS のダブルクォートを使って囲んでください。

agent-fs glob '**/*ai-tinkerers*'
agent-fs glob '**/*ai-tinkerers*' --path thoughts/research
agent-fs fts '"ai-tinkerers"'
agent-fs fts 'ai AND tinkerers'

FTS の引用符付き語句内にある引用符は、二重にしてエスケープします。バックスラッシュによるエスケープでは、FTS の引用符はエスケープされません。 ファイル名のパターンでは大文字と小文字が区別されます。全文検索ではインデックス化されたトークンが照合されるため、どちらのモードでもスペルミスは修正されません。

SQL クエリ（DuckDB）

コマンド	使用方法	説明
sql	agent-fs sql <query> [-t name=path[:format]]... [--max-rows <n>]	保存されたドキュメントに対して DuckDB SQL を実行します

対応形式：csv、tsv、parquet、xlsx、json、ndjson/jsonl（parquet/xlsx を除き、それぞれ .gz にも対応）、sqlite（.db／.sqlite／.sqlite3）、.duckdb。クエリ内で引用符付きドライブパスを使ってファイル形式のドキュメントを直接参照するか、-t を使って任意のドキュメントをテーブル名にバインドします。SQLite／DuckDB データベースには -t によるバインドが必要で、テーブルは <name>.<table> として公開されます。標準以外の拡張子を持つドキュメントをクエリするには、バインドに :format を追加します（例：-t logs=/raw/data.txt:csv）。クエリはサンドボックス内で実行され、ホストのファイルシステムやネットワークにはアクセスできません。結果は --max-rows 件（デフォルトは 1000 件、最大 10000 件）に制限されます。JSON 出力の truncated: true は、さらに行があることを示します。

コメント

コマンド	使用方法	説明
comment add	agent-fs comment add <path> --body <text> [--mention <user-id-or-email>]... [--line-start <n>] [--line-end <n>] [--quote <text> [--quote-prefix <text>] [--quote-suffix <text>]]	ファイルにコメントを追加します。--quote を使うと、編集後にウェブアプリが再検出する正確なテキストにコメントを固定できます。テキストが繰り返される場合は、プレフィックス／サフィックスで適切な箇所を指定します。ドライブのメンバーに通知するには、--mention を繰り返し指定します。
comment reply	agent-fs comment reply <comment-id> --body <text> [--mention <user-id-or-email>]...	コメントに返信し、必要に応じてドライブのメンバーにメンションします
comment list	agent-fs comment list [path] [--prefix <path>]	インライン返信とともにコメントを一覧表示します。ディレクトリ以下のすべてのコメントを表示するには、--prefix を使用します。位置引数のパスと --prefix は併用できません。
comment get	agent-fs comment get <id>	返信を含めてコメントを取得します
comment update	agent-fs comment update <id> --body <text> [--mention <user-id-or-email>]... [--clear-mentions]	コメントを更新し、必要に応じてメンションを置き換えるか、クリアします（投稿者のみ）
comment delete	agent-fs comment delete <id>	コメントを論理削除します（投稿者のみ）
comment resolve	agent-fs comment resolve <id>	コメントを解決済みにします
comment notifications	agent-fs comment notifications [--kind <comment|mention>]... [--unread] [--limit <n>]	現在のユーザーへの通知を一覧表示します。デフォルトの種類は comment です。
comment read	agent-fs comment read [ids...] [--all [--kind <comment|mention>]...]	選択した通知イベント ID、またはアクティブなドライブのすべての通知種類を既読にします。--all のデフォルトは comment です。

お気に入り

お気に入りはユーザーごとに管理されます。各ユーザーはドライブ内のファイルやフォルダーにスターを付け、自分のスターだけを表示できます。サーバーは API キーからユーザーを取得するため、ユーザー ID を受け取るコマンドはありません。閲覧者ロールで利用できます。

コマンド	使用方法	説明
favorite-add	agent-fs favorite-add <path>	ファイルまたはフォルダーにスターを付けます。同じ対象に 2 回スターを付けても何も起こりません。{ path, kind, createdAt, favorited } を返します。
favorite-remove	agent-fs favorite-remove <path>	自分のスターを削除します。パスが存在しなくなった場合でも機能します。{ path, removed } を返します。
favorite-list	agent-fs favorite-list	アクティブなドライブにある自分のお気に入りを、パス順に一覧表示します。フォルダーは末尾に / を付けて表示されます。

スターはファイルに追従します。mv はそのファイルに付けられたすべてのユーザーのスターを新しいパスに移動し、rm はスターを削除します。フォルダーがなくなる（最後のファイルが削除されるか、フォルダー外に移動される）と、そのフォルダーのスターも削除されます。

セットアップと認証

コマンド	使用方法	説明
onboard	agent-fs onboard [--local] [--filesystem] [--storage <minio|local>] [--storage-root <dir>] [-y] [--embeddings <provider>]	agent-fs（ストレージバックエンド＋データベース＋ユーザー）をセットアップします。--filesystem（または --storage local）を指定すると、ディスク上のバックエンドを使用します。Docker／S3 は不要です。--storage-root <dir> でディレクトリを指定します。
init	agent-fs init [--local] [-y]	onboard のエイリアスです
auth register	agent-fs auth register <email>	新しいユーザーを登録します
auth whoami	agent-fs auth whoami	現在のユーザー情報を表示します
auth reset-key	agent-fs auth reset-key	自分の API キーをリセットします。古いキーは直ちに使用できなくなります。

メンバー管理

コマンド	使用方法	説明
members	agent-fs members	アクティブなドライブのメンバーをユーザー ID、メールアドレス、表示名とともに一覧表示します。すべてのドライブメンバーが利用できます。ロールは表示されません。
member list	agent-fs member list	組織のメンバーを一覧表示します（ドライブのメンバーを表示するには --drive <id> を使用します）
member invite	agent-fs member invite <email> --role <role>	ユーザーを組織に招待します（viewer/editor/admin）
member update-role	agent-fs member update-role <email> --role <role>	組織のロールを更新します（ドライブのロールを更新するには --drive <id> を使用します）
member remove	agent-fs member remove <email>	組織からメンバーを削除します（ドライブからのみ削除するには --drive <id> を使用します）
member reset-key	agent-fs member reset-key <email>	メンバーの API キーをリセットします（組織の管理者のみ）。古いキーは直ちに使用できなくなります。

--drive フラグはグローバルオプションです。サブコマンドの前に指定してください：agent-fs --drive <id> member list。

members は viewer 権限で利用でき、ロールは返しません。member 管理コマンドは引き続き管理者権限が必要です。組織スコープのコマンドには組織の admin 権限が必要です。ドライブスコープのコマンド（--drive <id>）には、ドライブの admin 権限、またはそのドライブを所有する組織の管理者権限が必要です。また、ドライブは現在の組織に属している必要があります。管理者以外は権限エラーになります。所属していない組織 ID またはドライブ ID は「not found」を返します。

ドライブ管理

コマンド	使用方法	説明
drive list	agent-fs drive list	現在の組織のドライブを一覧表示します
drive create	agent-fs drive create <name>	新しいドライブを作成します（組織の管理者権限が必要です）
drive current	agent-fs drive current	現在のドライブのコンテキストを表示します
drive invite	agent-fs drive invite <email> --role <role>	ユーザーを招待します（viewer/editor/admin）

ドライブのメンバーシップは明示的です。drive list には、自分がメンバーになっているドライブのみが表示されます。ドライブを作成すると、自動的にそのドライブの admin メンバーになります。他のユーザーはドライブごとに招待する必要があります（組織への招待を通じて招待した場合は、デフォルトのドライブへのアクセス権が付与されます）。

設定とデーモン

コマンド	使用方法	説明
config get	agent-fs config get <key>	設定値を取得します（ドット記法：s3.bucket）
config set	agent-fs config set <key> <value>	設定値を設定します。embedding.provider を変更すると、以前のモデルと API キーが削除されます。
config list	agent-fs config list	すべての設定を表示します
config validate	agent-fs config validate	S3、データベース、認証、埋め込みの状態を確認します
daemon start	agent-fs daemon start	バックグラウンドデーモンを起動します
daemon stop	agent-fs daemon stop	デーモンを停止します
daemon status	agent-fs daemon status	デーモンが実行中かどうかを確認します

FUSE マウント（Linux のみ）

すべての組織ドライブを Linux FUSE ファイルシステムとして公開し、エージェントが通常のシェルコマンド（cat、grep、mv、rm）を使って agent-fs のコンテンツを操作できるようにします。/dev/fuse と SYS_ADMIN cap が必要です。macOS または gVisor ベースのサンドボックスでは利用できません。

次の 2 つのトポロジーに対応しています。

• ローカルモード（デフォルト）：ヘルパーが Unix ソケット経由でローカルデーモンと通信します。デーモンが起動しており、S3 バックエンドが設定されている必要があります。
• リモートモード（--remote）：ヘルパーがリモートの agent-fs HTTP API と直接通信します。ローカルデーモンは不要です。ホストされた agent-fs に接続できるものの、デーモン一式を実行できないサンドボックス（sprite、E2B、Hetzner VM、GitHub Actions ランナー）に最適です。

FUSE への書き込みには、ドライブで editor ロール以上が必要です。viewer のドライブでは、マウントはファイルへの書き込みが読み取り専用となります（書き込みは EACCES で失敗します。PERMISSION_DENIED レコードは <mount>/.agent-fs/errors.ndjson で確認してください）。

コマンド	使用方法	説明
mount	agent-fs mount <path> [--allow-other] [--foreground]	ローカルデーモン経由で <path> にドライブをマウントします（例：/mnt/agent-fs/<drive>/）。
mount --remote	agent-fs mount <path> --remote [--api-url <url>] [--api-key <key>]	リモートの agent-fs HTTP API にマウントします。フラグを省略した場合は、~/.agent-fs/config.json の apiUrl／apiKey、または AGENT_FS_API_URL／AGENT_FS_API_KEY 環境変数を読み込みます。--api-key より環境変数を優先してください（後者ではキーが ps に表示されます）。
umount	agent-fs umount <path>	FUSE マウントポイントをアンマウントします。
mount status	agent-fs mount status	マウントがアクティブかどうかと、その場所を表示します。

一般的なワークフロー

ドキュメントを保存して取得する

# Write a document (multi-line via stdin)
cat <<'EOF' | agent-fs write reports/q1-summary.md -m "Q1 summary draft"
# Q1 Summary
Revenue grew 15% quarter over quarter.
EOF

# Read it back
agent-fs cat reports/q1-summary.md

# Check metadata
agent-fs stat reports/q1-summary.md

ファイル全体を検索する

# Regex search within a specific path
agent-fs grep "revenue|growth" reports/

# Full-text search across all files (FTS5 — fast keyword matching)
agent-fs fts "quarterly revenue"

# Hybrid search (combines keyword + semantic matching — recommended default)
agent-fs search "financial performance metrics" --limit 5

# Vector-only semantic search (conceptual matches only)
agent-fs vec-search "financial performance metrics" --limit 5

--json を指定しない場合、PDF の検索結果ではスコアの後に [page N] が表示されます。画像の検索結果では、マーカーのスニペットが表示されます。

$ agent-fs search "revenue chart" --limit 3
/reports/q1.pdf (score: 1.000) [page 2]  by [email protected]
  Quarterly <b>revenue</b> grew 12% over Q4...

/charts/revenue.png (score: 0.492)  by [email protected]
  [image]

/decks/board.pdf (score: 0.484) [page 1]  by [email protected]
  [PDF page 1]

SQL でデータファイルをクエリする

# Query a CSV directly by path
agent-fs sql "SELECT category, sum(amount) AS total FROM '/finance/2026.csv' GROUP BY category" --json

# Join documents of different formats
agent-fs sql "SELECT s.name, t.tag FROM sales s JOIN tags t ON s.id = t.id" \
  -t sales=/data/sales.csv -t tags=/data/tags.parquet

# Query a stored SQLite database (tables exposed as app.<table>)
agent-fs sql "SELECT count(*) FROM app.users" -t app=/backups/app.db

# Pipe a query via stdin
echo "SELECT count(*) FROM '/data/events.ndjson'" | agent-fs sql

変更を確認して元に戻す

# View version history
agent-fs log docs/spec.md --limit 10

# Compare two versions
agent-fs diff docs/spec.md --v1 2 --v2 5

# Revert to version 2
agent-fs revert docs/spec.md --version 2

コメントとコラボレーション

# Add a comment to a file
agent-fs comment add docs/spec.md --body "Needs more detail on auth"

# Ask a human for a decision and send a targeted mention notification
agent-fs comment add docs/spec.md --body "Which option should we use?" --mention [email protected]

# Anchor a comment to exact text (survives edits above it; the MCP/API param is quote: { exact, prefix, suffix })
agent-fs comment add docs/spec.md --body "Which provider?" --quote "OAuth login" --quote-suffix " flow"

# Reply to a comment
agent-fs comment reply <comment-id> --body "Added in v3"

# List comments
agent-fs comment list docs/spec.md

# List unresolved comments below a directory
agent-fs comment list --prefix docs/

# Check unread notifications (the returned IDs are notification event IDs)
agent-fs comment notifications --unread --limit 20

# Check targeted mention notifications
agent-fs comment notifications --kind mention --unread

# Mark selected notifications as read
agent-fs comment read <notification-id> [<notification-id>...]

# Or acknowledge every notification in the active drive
agent-fs comment read --all

# Acknowledge every targeted mention notification in the active drive
agent-fs comment read --all --kind mention

# Resolve a comment
agent-fs comment resolve <comment-id>

新しいドライブを設定してユーザーを招待する

# Create a shared drive
agent-fs drive create "team-docs"

# Invite a teammate
agent-fs drive invite [email protected] --role editor

# Check current drive context
agent-fs drive current

メンバーを管理する

# List active-drive members without exposing roles
agent-fs members

# List org members
agent-fs member list

# List drive members
agent-fs --drive <driveId> member list

# Invite a user
agent-fs member invite [email protected] --role editor

# Change role
agent-fs member update-role [email protected] --role admin

# Remove from org (cascades to all drives)
agent-fs member remove [email protected]

# Remove from a specific drive only (keeps org membership)
agent-fs --drive <driveId> member remove [email protected]

最近のアクティビティを確認する

# What changed in the last hour?
agent-fs recent --since 1h

# Recent changes under a specific path
agent-fs recent docs/ --since 24h --limit 20

共有可能なダウンロードリンクを生成する

# Default expiry (24 hours)
agent-fs signed-url docs/report.pdf

# Custom expiry (1 hour)
agent-fs signed-url docs/report.pdf --expires-in 3600

# Render in the browser instead of downloading (PDF viewer, image tab)
agent-fs signed-url docs/report.pdf --inline

# JSON output (useful for agents)
agent-fs signed-url docs/report.pdf --json
# → { "url": "https://...", "path": "/docs/report.pdf", "expiresIn": 86400, "expiresAt": "2026-03-20T..." }

S3／MinIO バックエンド（kind: "presigned"）では、URL に認証は不要です。リンクを知っている人なら誰でも、有効期限が切れるまでファイルをダウンロードできます。アクセス権の RBAC チェックは生成時にのみ行われます（ドライブで viewer 以上）。その後は URL がベアラーシークレットになります。ログに記録したり、認証情報を貼り付けない場所に貼り付けたりしないでください。また、実用上可能な限り短い --expires-in を使用してください。署名付き URL は、ファイル拡張子に応じた正しい Content-Type ヘッダー（例：.pdf には application/pdf、.png には image/png）を返します。デフォルトでは Content-Disposition: attachment も付与されるため、リンクを開くと実際のファイル名でファイルが保存されます。PDF を <iframe> で表示する場合など、リンクを埋め込んだり閲覧用に開いたりする場合は、--inline（API："disposition": "inline"）を指定してください。<img> タグでは、どちらの場合も disposition は無視されます。

署名付き URL に対応していないバックエンド（ローカルファイルシステムのバックエンド）では、signed-url は失敗しません。代わりに、<appUrl>/file/~/<org>/<drive>/<path> 形式の認証済みアプリ内リンク（kind: "app"、expiresIn: 0）にフォールバックします。署名付き URL とは異なり、このリンクは公開されたベアラーシークレットではありません。デーモンの /raw ルートとウェブビューアーではサインインが必要なため、受信者はドライブの認証済みメンバーである必要があります。リンクがデプロイ先を指すように、AGENT_FS_APP_URL（または設定内の appUrl）を設定してください。

アカウントを持っていない人とファイルを共有する

# 24h link, opens as many times as needed
agent-fs share-create docs/report.md

# Single-use link: the page opens once, then shows "link expired"
agent-fs share-create docs/report.pdf --one-off

# At most 5 views, valid for 1 hour
agent-fs share-create docs/report.pdf --max-views 5 --expires-in 3600

# Kill a link (id from share-create), or every link to a file
agent-fs share-revoke <id>
agent-fs share-revoke --path docs/report.pdf

share-create は Web アプリではなく API ホスト（https://<server>/share/<token>）の URL を返すため、サインインしていない人でも利用できます。signed-url とは異なり、受信者にはレンダリングされたページが表示されます。Markdown はサニタイズ済み HTML（フロントマターカード、目次、コールアウト、タスクリスト、脚注、数式、mermaid 図、シンタックスハイライト付きコード、ライト／ダーク／システムテーマ、ソース表示とコピー）に変換され、テキストとコードはエスケープして表示されます。画像、PDF、音声、動画は埋め込まれ、HTML ページはサンドボックス化されたフレーム内に表示されます（「全ページを開く」リンク付き）。それ以外のファイル形式では、プレビューなしのカードが表示されます。各ページにはファイル名、サイズ、有効期限、ダウンロードボタンが表示されます。SVG ファイルはレンダリングされず、ダウンロードのみ可能です。

共有する前に知っておきたいこと：

• リンクはベアラーシークレットです。 リンクを知っている人なら誰でも、有効期限が切れるか、取り消されるか、閲覧回数の上限に達するまで開くことができます。リンクは一度だけ表示され、保存されるのは SHA-256 のみのため、復元できません。取り消す必要がある場合に備えて、id を控えておいてください。
• ファイルのスナップショットではなく、現在の内容が表示されます。 ファイルを編集すると、リンクには新しいバージョンが表示されます。ファイルを削除または移動すると、リンクには「ファイルを利用できません」と表示されます。
• --one-off／--max-views が数えるのはページの閲覧回数であり、ファイルのデータもその閲覧に紐づきます。 閲覧回数に制限のあるリンクでは、URL だけでファイルを取得することはできません。閲覧回数を消費したページには、埋め込みコンテンツとダウンロードボタンが使用する、最大 1 時間（ただしリンクの有効期限を超えない）の非公開で短期間有効な認証情報が付与されます。閲覧回数を使い切ると、リンクしか持っていない人は誰もファイルを取得できません。また、リンクを取り消すか有効期限が切れると、すべての認証情報が即座に無効になります。無制限のリンクには認証情報は不要です。リンクプレビュー用のクローラー（Slack、WhatsApp など）や HEAD リクエストでは、閲覧回数は消費されません。
• 共有した HTML ファイルからアクセスできるのは、そのファイルだけです。 不透明なオリジンを持つサンドボックス内で実行されるため、同じ場所にある相対パスのアセット（chart.png、app.js）は 404 を返します。ページでそれらが必要な場合は、代わりにフォルダーを共有してください（下記）。
• パスはドライブの内側に収まっている必要があります。 share-create は、. または .. のセグメントを含むパス（スラッシュの向きは問いません）を解決せずに拒否します。
• 閲覧者ロールでもリンクを作成できます。 作成者（またはドライブ管理者）はリンクを取り消せます。カウント対象となった閲覧はすべて share_viewed イベントとして記録されます。
• プロキシの背後にサーバーがあり、Host／X-Forwarded-* が転送されない場合は、AGENT_FS_PUBLIC_URL を設定して、返されるリンクが正しいアドレスを指すようにしてください。

アップロード時の MIME タイプ： write、edit、append、revert は、ファイル拡張子に基づいて S3 オブジェクトの正しい Content-Type を自動検出して設定します。コンテンツタイプはデータベースにも保存され、stat の出力では contentType フィールドから確認できます。標準入力および --file によるアップロードでは、バイト列がそのまま保持されます。検索では、有効なインデックス可能な UTF-8 テキストと、抽出された PDF テキストがインデックス化されます。

フォルダーから HTML サイトを公開する

# index.html is the site's front page (without one, a lone .html page opens, or else a list of the HTML pages)
agent-fs write report-site/index.html --content '<!doctype html><link rel="stylesheet" href="style.css"><img src="chart.png"><script src="app.js"></script>'
agent-fs share-create report-site --expires-in 86400
# Site: https://<server>/site/<token>/

# Take the site down
agent-fs share-revoke --path report-site

フォルダーに対する share-create は、kind: "site" と API ホスト上の /site/<token>/ URL を返します。リンクを知っている人は、サインインせずに開くことができます。

• エントリーポイントは index.html です。 /site/<token>/ はフォルダーの index.html を配信し、sub/ は sub/index.html を配信します。index.html がないフォルダーの場合、.html ファイルが1つだけならそれを開き（例：radar.html）、それ以外の場合は HTML ページを一覧表示します（ほかのファイルやサブフォルダーは表示しません）。HTML ページがないフォルダーでは 404 が返されます。
• 相対パスを使用できます。 <img src="chart.png">、<link href="style.css">、<script src="app.js">、モジュールスクリプト、fetch("data.json")、CSS の url() はすべてフォルダー内で解決されます。外部 CDN やフォントも読み込まれます。
• ページは不透明なオリジンのサンドボックスで実行されます。 スクリプト、フォーム、ポップアップ、アラートは動作しますが、localStorage、sessionStorage、Cookie は使用できません。
• 表示回数の制限はありません。 1回のページ読み込みで多数のファイルを取得するため、フォルダーでは --max-views と --one-off は使用できず、サイトの表示では share_viewed イベントも記録されません。代わりに --expires-in（最大7日間）と share-revoke --path <folder> を使用してください。
• リンクが有効な間、ページはフォルダー内のすべてのファイルを読み取ることができます。 公開する HTML の隣に秘密情報を置かないでください。また、自分が作成していない HTML が含まれるフォルダーは公開しないでください。ライブ UI でも .html ファイルは同じ方法で表示され、そのファイルのフォルダーに対するサイトリンクの有効期間は15分です。
• 各ファイルは最大25 MBまで配信されます。それを超えるファイルには 413 が返されます。

レスポンス内のアプリ URL

AGENT_FS_APP_URL が設定されている場合（例：https://live.agent-fs.dev）、ファイル関連の ops には、ライブウェブアプリ内のファイルを指す appUrl フィールドが自動的に含まれます。

AGENT_FS_APP_URL=https://live.agent-fs.dev agent-fs stat docs/report.pdf --json
# → { ..., "appUrl": "https://live.agent-fs.dev/file/~/org-id/drive-id/docs/report.pdf" }

これは、path または to フィールドを返すすべての op（write、stat、edit、append、rm、cp、mv、signed-url など）に適用されます。

セットアップを検証する

agent-fs config validate

サンドボックスからリモートドライブをマウントする

エージェントが Linux サンドボックス（sprite、E2B、Hetzner VM、GitHub Actions runner など）で実行されており、ホストされた agent-fs HTTP API には接続できるものの、完全なデーモンと S3 スタックをローカルで実行できない場合は、--remote を使用します。

# Linux prereqs (run once per sandbox)
sudo apt-get install -y fuse3
sudo chmod 666 /dev/fuse
sudo ln -sf /proc/mounts /etc/mtab
echo user_allow_other | sudo tee -a /etc/fuse.conf

# Auth — either env vars or ~/.agent-fs/config.json
export AGENT_FS_API_URL=https://agent-fs.example.com
export AGENT_FS_API_KEY=<key>

# Mount — no local daemon needed
mkdir -p ~/mnt
agent-fs mount ~/mnt --remote

# Use plain shell verbs against remote content
ls ~/mnt
cat ~/mnt/current/docs/spec.md
echo "edit from sandbox $(date)" > ~/mnt/current/notes.txt

# Unmount
fusermount3 -u ~/mnt

環境ごとのガイドについては、docs/mounting/ を参照してください（sprite、E2B、Hetzner）。

アップロード上限の設定

生の HTTP アップロードの既定値は 50 MiB です。上限を変更するには、サーバーで AGENT_FS_MAX_UPLOAD_BYTES を設定し（例：100 MiB の場合は 104857600）、デーモンを再起動してください。無効な値の場合は 50 MiB に戻ります。ウェブ UI は /health から上限を取得します。 JSON/MCP の write の上限は 10 MiB のままです。FUSE では、プロトコルのオーバーヘッドを含めて、エンコード済み IPC フレームの上限は 64 MiB です。それを超えるファイルには、生の HTTP アップロードを使用してください。

自分のプロフィール

agent-fs profile get は自分のプロフィールを読み取ります。agent-fs profile set --name "Taras" は表示名を設定します。名前は前後の空白が削除され、1～100文字に制限されます。コメントを読める人なら誰でも表示名を確認できます。編集できるのは認証済みの自分のプロフィールのみです。 HTTP：GET /auth/profile、PATCH /auth/profile（{ "displayName": "Taras" } を指定。クリアする場合は null）。 MCP：profile-get、profile-set（displayName を指定）。 ウェブのアカウントメニューには プロフィールを編集 があります。コメントのレスポンスには設定されている場合 authorDisplayName が含まれ、通知のレスポンスには actorDisplayName が含まれます。すべてのドライブメンバーは、agent-fs members でメンバーのメールアドレスと表示名を一覧表示できます。メンバーのロールを確認できるのは引き続き管理者のみです。