# AnyFS CLI Command Reference

Complete reference for every `anyfs` CLI command, including all flags, options, and output formats.

## Core Commands

### `anyfs init`

Initialize AnyFS global state. Creates `~/.anyfs/` directory, generates a cryptographic
identity (`user_id` + `device_id`), a 256-bit root key (AES-256-GCM encrypted), and a
recovery bundle.

```bash
anyfs init
```

Output:
```json
{
  "global_root": "/home/user/.anyfs",
  "identity": {
    "user_id": "usr_4ad51f4a4687",
    "device_id": "dev_3f2d95fda79e",
    "created_at": "2026-04-06T..."
  }
}
```

Safe to run multiple times (idempotent). First run generates keys; subsequent runs are no-ops.

---

### `anyfs doctor`

Run workspace diagnostics to verify AnyFS is correctly configured.

```bash
anyfs doctor --workspace .
```

Checks: global state, identity, root key, workspace state, agent registration.

---

### `anyfs capture <agent-type>`

Extract agent state files from the workspace and classify them into namespaces.

```bash
anyfs capture claude-code --workspace /path/to/project
anyfs capture codex-cli -w .
anyfs capture gemini-cli -w .
anyfs capture openclaw -w .
anyfs capture opencode -w .
```

**Arguments:**
- `agent-type` (positional, default: `claude-code`) - Agent type to capture. Supported: `claude-code`, `codex-cli`, `gemini-cli`, `hermes`, `nanobot`, `openclaw`, `opencode`.

**Options:**
- `-w, --workspace` (default: current directory) - Workspace path.

**What it captures for Claude Code:**
- `CLAUDE.md` in workspace root -> `skills` namespace
- `~/.claude/projects/<encoded-workspace>/` session files -> `process` namespace
- Memory files in the project directory -> `memory` namespace
- Files matching `*soul*`, `*instruction*`, `*prompt*` patterns -> corresponding namespaces

**What it captures for other clients:**
- `codex-cli` -> native session JSONL files plus global/workspace `AGENTS.md`, skills, prompts, rules, plugins, and memories
- `gemini-cli` -> native session JSON files plus `GEMINI.md` and global/workspace skills
- `openclaw` -> native session store/transcripts plus OpenClaw workspace guidance and agent instruction files
- `opencode` -> native exported sessions plus local/global skills and workspace guidance

**Artifacts rule:** `artifacts` are for final outputs that you want people to inspect or consume directly, such as a generated PDF, rendered video, exported report, chart pack, or dataset bundle. They are not a bucket for source code, dependency directories, caches, or arbitrary workspace files.

**Privacy default:** client-global runtime config files such as `settings.json`, `config.toml`, `projects.json`, `openclaw.json`, and `opencode.json` are excluded from capture by default. AnyFS only keeps migratable context, not machine-local auth/runtime configuration.

Output:
```json
{
  "ok": true,
  "agent_id": "agt_e0469686de67",
  "agent_type": "claude-code",
  "workspace": "/home/user/project",
  "captured_namespaces": ["memory", "skills", "process"],
  "payloads": { "memory": [...], "skills": [...], "process": [...] }
}
```

---

### `anyfs snapshot create`

Encrypt the latest capture into an immutable snapshot. Each private namespace payload is
encrypted with a unique DEK (Data Encryption Key), which is itself wrapped with the root key.

```bash
anyfs snapshot create --workspace .
anyfs snapshot create -w . --artifacts-private
```

**Options:**
- `-w, --workspace` (default: current directory)
- `--artifacts-public / --artifacts-private` (default: `--artifacts-public`) - Control whether `artifacts` stay unencrypted inside the snapshot/share flow

Output:
```json
{
  "snapshot_id": "snp_823f3819d780",
  "agent_id": "agt_e0469686de67",
  "namespace": ["memory", "skills", "process"],
  "encrypted": true,
  "created_at": "2026-04-06T..."
}
```

Snapshot files stored in `.anyfs/exports/snapshots/<snapshot_id>/`:
- `artifacts/public/` - Unencrypted public artifacts
- `payloads/private/` - AES-256-GCM encrypted envelopes per namespace

Keep `artifacts/public/` focused on end-user deliverables. Code and workspace files belong in `code_ref`, `workspace_overlay`, or private trajectory data, not in public artifacts.

This flag only affects snapshot/share payload layout. Publish-time visibility is controlled
separately by the publish visibility policy used by `anyfs pack` and `anyfs publish`.

---

### `anyfs snapshot list`

List all snapshots for the workspace.

```bash
anyfs snapshot list -w .
```

---

### `anyfs restore`

Decrypt and restore a snapshot to the workspace.

```bash
anyfs restore --snapshot latest -w .
anyfs restore --snapshot snp_823f3819d780 -w .
```

**Options:**
- `-s, --snapshot` (default: `latest`) - Snapshot ID or "latest"
- `-w, --workspace` (default: current directory)

Restored files are placed in `.anyfs/exports/restores/<snapshot_id>/`.

---

### `anyfs quick-share`

Compatibility alias for `anyfs share`.

One-shot command: capture -> snapshot -> encrypt -> upload via the storage gateway -> return shareable links.

```bash
anyfs quick-share --workspace . --password MySecretPass --message "Resume this in the anyfs repo"
anyfs quick-share -w . -n memory,skills -p MyPass -m "Review the session only"
anyfs quick-share -w . --agent-type codex-cli -m "Restore workspace and continue"
```

**Options:**
- `-w, --workspace` (default: current directory)
- `-n, --namespaces` - Comma-separated namespace list (default: all private namespaces)
- `-p, --password` - Share password (auto-generated 16-char alphanumeric if omitted)
- `-m, --message` (required) - Handoff note from the sending agent to the recipient
- `--workspace-mode` (default: `changed`) - Workspace payload mode: `changed`, `full`, `none`
- `--process-scope` (default: `current`) - Process capture scope: `current` or `all`
- `--artifacts-public / --artifacts-private` (default: `--artifacts-public`) - Control whether `artifacts` remain public inside the generated snapshot/share payload
- `-t, --agent-type` (default: `claude-code`) - Agent type for capture (`claude-code`, `codex-cli`, `gemini-cli`, `hermes`, `nanobot`, `openclaw`, `opencode`)

By default, `quick-share` also emits a `workspace` share containing a restorable workspace bundle in `changed` mode.
By default, process capture includes only the current session when the harness exposes one, or the
closest official equivalent when it does not. Use `--process-scope all` to include every matching
session.

Current-session behavior:
- `codex-cli`: exact current thread via `CODEX_THREAD_ID` when available; otherwise newest workspace session.
- `claude-code`: exact session if `ANYFS_CLAUDE_SESSION_ID`/`ANYFS_CURRENT_PROCESS_ID` is set; otherwise Claude's documented "most recent conversation in the current directory" approximation.
- `gemini-cli`: exact session if `ANYFS_GEMINI_SESSION_ID`/`ANYFS_CURRENT_PROCESS_ID` is set; otherwise newest workspace chat using Gemini's own session metadata.
- `openclaw`: exact session via `ANYFS_OPENCLAW_SESSION_ID`, or active session mapping via `ANYFS_OPENCLAW_SESSION_KEY`; otherwise newest workspace-matching session using `sessions.json` metadata.
- `opencode`: exact session if `ANYFS_OPENCODE_SESSION_ID`/`ANYFS_CURRENT_PROCESS_ID` is set; otherwise the newest workspace session from `opencode session list --format json`.
- `hermes`: exact session if `ANYFS_HERMES_SESSION_ID`/`ANYFS_CURRENT_PROCESS_ID` is set; otherwise the same "most recent CLI session" concept as `hermes --continue`.
- `nanobot`: exact session if `ANYFS_NANOBOT_SESSION_KEY`/`ANYFS_CURRENT_PROCESS_ID` is set; otherwise newest workspace session using session metadata from `workspace/sessions/*.jsonl`.

These environment variables are optional. They are only for pinning one exact session when the
automatic current-session selection is not the one you want.

Output:
```json
{
  "snapshot_id": "snp_ed43b33cac45",
  "password": "MySecretPass",
  "message": "Resume this in the anyfs repo",
  "workspace_mode": "changed",
  "shares": {
    "process": {
      "cid": "3f4f9b...",
      "gateway_url": "https://storage.anyfs.ai/raw/3f4f9b...",
      "share_file": "/path/to/.anyfs/exports/shares/snp_xxx.process.share.json"
    },
    "workspace": {
      "share_file": "/path/to/.anyfs/exports/shares/wsp_xxx.workspace.share.json"
    }
  },
  "instructions": "Recipient runs: anyfs register --type <their-client> <display-name> (if needed), then anyfs open <file_or_url> -p MySecretPass --type <their-client>"
}
```

CID and `gateway_url` are included when `storage_gateway_url` is configured. In GCS-backed
deployments, the gateway URL is typically the storage gateway's public raw blob URL.
Auto-initializes the workspace and registers the agent if needed.

---

### `anyfs resume`

Resume a session from one agent harness in another.

`resume` is optional. The normal receiving flow is:

```text
share -> open -> read or resume
```

After `anyfs open`, the recipient already has a readable context package on disk. Use
`resume` only when the target client should adopt that context as a native session.

Practical rule:
- for collaboration, review, or understanding, reading the restored session files directly is enough
- for reusing that context inside the target client and continuing the conversation there, use `resume`

```bash
# Native resume (full transcript replay)
anyfs resume session.jsonl --target codex-cli --source claude-code -w .
anyfs resume https://storage.anyfs.ai/raw/<cid> --target opencode --password SharedPass -w .

# Context-only injection (summary written to instruction file)
anyfs resume session.jsonl --target cursor --context-only -w .
```

**Arguments:**
- `transcript_path` (positional, required) - Path to transcript file, canonical process bundle, or share URL/file

**Options:**
- `-t, --target` (required) - Target agent: `claude-code`, `codex-cli`, `gemini-cli`, `hermes`, `nanobot`, `openclaw`, `opencode`, `cursor`
- `-s, --source` - Source agent type (auto-detected if omitted)
- `-w, --workspace` (default: current directory)
- `-p, --password` - Share password when `transcript_path` is a share URL or `.share.json`
- `--native / --context-only` (default: `--native`) - Resume mode

**Native mode**: Generates a real native transcript file the target client can load as a
previous session with full tool call history.

**Context-only mode**: Injects a compressed context summary into the target's instruction file:
- Claude Code: `CLAUDE.md`
- Cursor: `.cursor/rules/resumed-session.mdc`
- Gemini: `GEMINI.md`

If the user only needs to understand or continue the work, it is often simpler to stop at
`anyfs open` and read the restored files directly.

---

### `anyfs migrate`

Import migratable context from one client format into another on the same machine.

```bash
anyfs migrate --from claude-code --to codex-cli -w .
anyfs migrate --from codex-cli --to gemini-cli -w /src --target-workspace /dst --dry-run
```

**Options:**
- `--from` (required) - Source agent type
- `--to` (required) - Target agent type
- `-w, --workspace` - Source workspace
- `--target-workspace` - Target workspace (defaults to `--workspace`)
- `--preset` - Migration preset: `user-data` (default) or `full`
- `--include-secrets / --no-include-secrets` - Include or exclude source runtime secrets and provider keys
- `--dry-run` - Preview import plan without writing files
- `--overwrite` - Overwrite existing imported files

Outputs an import report with:
- `import_root`
- `guidance_file`
- `planned_items`
- `applied_files`
- `resume_sessions`
- `preset`
- `include_secrets`
- `redacted_items`
- `secret_items`

---

### `anyfs buy`

Fork a published package, install it locally, and optionally resume its process context.

```bash
anyfs buy pkg_123 --workspace . --child-display-name my-fork
anyfs buy pkg_123 --workspace . --resume codex-cli
```

**Options:**
- `-w, --workspace` - Local workspace owning the buyer agent
- `--child-display-name` - Name used for the forked child package
- `-o, --output` - Install output directory
- `-r, --resume` - Optional target agent for immediate resume

---

## Share Commands

### `anyfs share namespace <namespace>`

Share a single namespace with a password. Re-wraps the DEK with a password-derived key
so the recipient can decrypt without your root key.

```bash
anyfs share namespace memory -w . -p SecretPass -m "Review the memory state" --snapshot latest
anyfs share namespace workspace -w . -p SecretPass -m "Restore changed files and continue"
```

**Arguments:**
- `namespace` (positional, required) - Namespace to share (memory, soul, skills, process, workspace)

**Options:**
- `-p, --password` (required) - Password for the recipient
- `-m, --message` (required) - Handoff note from the sending agent to the recipient
- `--workspace-mode` (default: `changed`) - Workspace payload mode when sharing `workspace`
- `-w, --workspace` (default: current directory)
- `-s, --snapshot` (default: `latest`) - Snapshot ID

Output includes `share_file` path and optionally `cid` / `gateway_url` if a storage gateway is configured.

---

### `anyfs share open <share-path>`

Decrypt a shared file using only the share password. No root key needed.

```bash
anyfs share open /path/to/snp_xxx.memory.share.json -p SecretPass
anyfs share open https://storage.anyfs.ai/raw/<cid> -p SecretPass
```

`share open` is the primary receiving action. It restores a readable context package that
another agent can inspect directly as files. Native `resume` is a follow-up step only when
the target client should load the context into its own session store.

**Arguments:**
- `share_path` (positional, required) - Path to `.share.json` file or IPFS URL

**Options:**
- `-p, --password` (required) - Password from the sender
- `-o, --output` - Output directory (default: temp directory for URLs or explicit output directory)

Output:
```json
{
  "namespace": "memory",
  "output_file": "/path/to/memory.json",
  "item_count": 27,
  "message": "Review the memory state"
}
```

When opening a `workspace` share, AnyFS restores files into `OUTPUT/workspace/` and returns both `output_file` and `restore_dir`.

---

### `anyfs share list`

List all share links for the workspace.

```bash
anyfs share list -w .
```

---

## Backup & Publishing Commands

### `anyfs backup`

Upload encrypted snapshot payloads to the cloud (API metadata + storage gateway blob storage).

```bash
anyfs backup --workspace . --snapshot latest
anyfs backup -w . -s snp_xxx -n memory,skills
```

**Options:**
- `-w, --workspace` (default: current directory)
- `-s, --snapshot` (default: `latest`)
- `-n, --namespaces` - Comma-separated namespace filter

---

### `anyfs pack`

Build an AFPKG archive (ZIP) from a snapshot. Contains manifest, public artifacts,
encrypted private payloads, lineage metadata, and policy.

```bash
anyfs pack -w .
anyfs pack snp_xxx -w . --output /tmp/my-package.afpkg
```

**Arguments:**
- `snapshot_id` (positional, optional) - Snapshot ID (default: latest)

**Options:**
- `-w, --workspace` (default: current directory)
- `-o, --output` - Output file path
- `--public` - Comma-separated namespaces to publish as public
- `--private` - Comma-separated namespaces to publish as private
- `--visibility-policy` - Optional path to a publish visibility policy file

Visibility policy v1 only applies here and in `anyfs publish`. Default behavior remains:
- `artifacts` -> `public`
- all other namespaces -> `private`

Workspace policy file path:

```text
.anyfs/visibility.json
```

Example:

```json
{
  "version": 1,
  "publish": {
    "default": "private",
    "namespaces": {
      "artifacts": "private"
    }
  }
}
```

CLI precedence is:
1. `--public` / `--private`
2. `.anyfs/visibility.json`
3. built-in default

v1 boundary:
- only `artifacts` may be marked `public`
- trying to publish `process`, `skills`, `workspace`, or other namespaces as `public` is rejected

---

### `anyfs publish`

Publish a package to the AnyFS registry. Uploads the AFPKG archive to the configured
blob backend via the storage gateway and registers metadata on the API.

```bash
anyfs publish -w .
anyfs publish /path/to/package.afpkg -w .
anyfs publish -w . --private artifacts
anyfs publish -w . --visibility-policy ./.anyfs/visibility.json
```

Auto-packs the latest snapshot if no archive path is provided.

**Options:**
- `-w, --workspace` (default: current directory)
- `--public` - Comma-separated namespaces to publish as public
- `--private` - Comma-separated namespaces to publish as private
- `--visibility-policy` - Optional path to a publish visibility policy file

If you pass an existing `.afpkg`, visibility overrides are rejected. Apply them at pack time
instead, or omit the archive path so `publish` can auto-pack with the requested policy.

---

### `anyfs fork`

Fork a published package, creating a child package with lineage tracking.

```bash
anyfs fork pkg_abc123 --child-display-name "my-fork" -w .
```

---

### `anyfs release create`

Create a versioned release from a published package.

```bash
anyfs release create pkg_abc123 --version 1.0.0 -w .
```

---

### `anyfs lineage show`

Display the fork history (parent-child lineage) of a package.

```bash
anyfs lineage show pkg_abc123 -w .
```

---

## Authentication & Agent Commands

### `anyfs auth login`

Login with email to obtain an API authentication token.

```bash
anyfs auth login --email user@example.com
```

Stores the token in `~/.anyfs/config.json`.

---

### `anyfs agent register`

Register an agent for a workspace. Creates `.anyfs/` in the workspace and binds the agent.

```bash
anyfs agent register claude-code -w .
anyfs agent register openclaw -w . --display-name "My Agent" --no-remote
```

**Arguments:**
- `agent_type` (positional, default: `claude-code`)

**Options:**
- `-w, --workspace` (default: current directory)
- `--display-name` - Custom agent display name
- `--remote / --no-remote` (default: `--remote`) - Also register on remote API

---

### `anyfs agent status`

Check local and remote agent status for the workspace.

```bash
anyfs agent status -w .
```

---

### `anyfs agent bind`

Bind a standalone agent to a user account using the user's email and password. Publish requires a bound account.

```bash
anyfs agent bind --email you@example.com --password '<password>' -w .
```

---

## Recovery Commands

### `anyfs export-recovery`

Export a recovery key bundle for backup. Contains encrypted identity + root key.

```bash
anyfs export-recovery
anyfs export-recovery --output /path/to/backup.anyfs
```

---

### `anyfs import-recovery`

Import a recovery key bundle to restore identity and root key on a new device.

```bash
anyfs import-recovery /path/to/recovery.anyfs
```

---

## Directory Structure

### Global State (`~/.anyfs/`)

```
~/.anyfs/
  identity.json          # user_id, device_id
  config.json            # API URLs, tokens
  keys/
    rootkey.enc          # Encrypted root key (AES-256-GCM)
    recovery.anyfs       # Recovery bundle
  agents/
    registry.json        # Registered machine-level agents
    <agent_type>.json    # Global agent record for this client type
    <agent_type>.key     # Global private key for this client type
    remote/
      <agent_type>.json  # Remote binding / API metadata for this client type
  db/
    local.db             # SQLite key-value store
```

### Workspace State (`.anyfs/`)

```
.anyfs/
  workspace.json         # Workspace metadata
  state/
    capture.json         # Latest capture result
    snapshots.json       # Snapshot records
    backups.json         # Backup records
    links.json           # Share links
    packages.json        # Published packages
    releases.json        # Releases
    lineage.json         # Fork history
  manifests/
    <snapshot_id>.json   # Snapshot manifests
  exports/
    snapshots/<id>/      # Encrypted snapshot payloads
    shares/              # Password-protected share files
    restores/<id>/       # Decrypted restored files
    <id>.afpkg           # Packaged archives
```