Skip to main content

Aether CLI Reference

This page is generated from packages/aether-cli Clap definitions.

  • Generated on: 2026-03-14T04:28:25Z
  • Regenerate with: bash scripts/docs/sync-aether-cli-reference.sh

aether​

AetherFS Aether client runtime

Usage: aether [OPTIONS] [COMMAND]

Commands:
  mount        Mount the Aether filesystem (default command)
  status       Display runtime status and health summary
  doctor       Run local preflight checks for FUSE and mount readiness
  stop         Request a graceful shutdown of a running Aether mount
  cache        Inspect shared cache state (experimental)
  journal      Inspect and tune journal durability knobs (experimental)
  prefetch     Inspect prefetch activity (experimental)
  config       Inspect or update configuration (experimental)
  fallback     Inspect fallback toggles or flip them (experimental)
  metrics      Inspect metrics configuration (experimental)
  trace        Capture tracing telemetry (experimental)
  logs         Inspect runtime logs
  debug        Inspect live runtime state (experimental)
  fuse         Check and clean up FUSE mounts and orphaned processes
  completions  Generate shell completion scripts for the aether CLI
  transport    Inspect and tune remote transport settings
  wal          Inspect and replay remote WAL records
  help         Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether mount​

Mount the Aether filesystem (default command)

Usage: aether mount [OPTIONS]

Options:
      --config <FILE>
          Path to configuration file (defaults to ./aether.toml when present)
      --mount-dir <PATH>
          Directory where the filesystem will be mounted
      --quiet
          Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>
          Session identifier that the client should mount
      --server-addr <ADDR>
          Compatibility server address override (overrides aether.toml `server_addr`); bridge mounts use `bridge.server_endpoint`
      --verbose...
          Increase logging verbosity (repeat for trace level)
      --bridge-client-name <NAME>
          Bridge client name
      --color <WHEN>
          Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --bridge-enabled
          Enable bridge mode (replaces AFS_AETHER_BRIDGE_ENABLED)
      --json
          Enable JSON output when supported by the selected command
      --log-level <LOG_LEVEL>
          Log level for the client (overrides configuration/env) [possible values: error, warn, info, debug, trace]
      --trace-id <TRACE_ID>
          Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>
          Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --control-socket <PATH>
          Override path to the control socket used by auxiliary CLI commands
      --auth-token-file <PATH>
          Read auth token from file
      --metrics-addr <ADDR>
          Prometheus metrics socket (ip:port)
      --allow-other
          Allow other users to access the mount
      --auth-token-stdin
          Read auth token from stdin
      --mount-option <FLAG>
          Additional FUSE mount option (key or key=value)
      --server <ADDR>
          Remote server endpoint for transport/WAL operations
      --cache-dir <PATH>
          Base directory for cache data (overrides AFS_AETHER_CACHE_DIR)
      --transport <TRANSPORT>
          Remote transport protocol (grpc or quic) [possible values: grpc, quic]
      --cache-shared-root <PATH>
          Shared cache root directory (defaults to <cache-dir>/shared; overrides AFS_AETHER_CACHE_SHARED_ROOT)
      --no-cache-shared-root
          Disable host-wide shared cache dedupe (ignore default shared cache root)
      --read-only
          Reject all write operations and expose the session in read-only mode (overrides AFS_AETHER_READ_ONLY)
      --dispatcher-capacity <CAPACITY>
          Bounded dispatcher queue capacity (overrides AFS_AETHER_DISPATCH_CAPACITY)
      --dispatcher-queue-timeout-ms <MILLISECONDS>
          Maximum milliseconds to wait for dispatcher capacity before failing the operation (overrides AFS_AETHER_FUSE_QUEUE_TIMEOUT_MS)
      --dispatcher-max-write-streak <COUNT>
          Maximum number of consecutive write-priority dequeues before reads are serviced (overrides AFS_AETHER_DISPATCH_MAX_WRITE_STREAK)
      --metadata-ttl <SECONDS>
          Metadata cache TTL in seconds (overrides AFS_AETHER_LOOKUP_TTL_SECS)
      --negative-lookup-ttl <SECONDS>
          Negative lookup cache TTL in seconds (overrides AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS)
      --dir-cache-ttl <SECONDS>
          Directory cache TTL in seconds (overrides AFS_AETHER_DIR_CACHE_TTL_SECS)
      --shutdown-timeout-secs <SECONDS>
          Grace period in seconds before shutdown is forced (overrides AFS_AETHER_SHUTDOWN_TIMEOUT_SECS)
      --writeback-cache <MODE>
          Kernel writeback cache mode (auto, on, off; overrides aether.toml writeback_cache_mode) [possible values: auto, on, off]
  -h, --help
          Print help
  -V, --version
          Print version

aether status​

Display runtime status and health summary

Usage: aether status [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Render the status report as JSON
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether doctor​

Run local preflight checks for FUSE and mount readiness

Usage: aether doctor [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether stop​

Request a graceful shutdown of a running Aether mount

Usage: aether stop [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --session-id <SESSION>    Session identifier of the running mount
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --socket <SOCKET>         Explicit control socket path to contact [aliases: --control-socket]
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether cache​

Inspect shared cache state (experimental)

Usage: aether cache [OPTIONS] <COMMAND>

Commands:
  hosts    Show shared cache usage with host totals and per-session breakdown
  clear    Clear cached blobs and reset derived cache metadata for a session
  inspect  Inspect cache pressure signals and dirty coverage
  help     Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether cache hosts​

Show shared cache usage with host totals and per-session breakdown

Usage: aether cache hosts [OPTIONS]

Options:
      --cache-dir <DIR>
          Override cache directory base (defaults to config cache_dir)
      --config <FILE>
          Path to configuration file (defaults to ./aether.toml when present)
      --json
          Render the host registry summary as JSON
      --quiet
          Suppress routine output (sets log level to error, overrides verbose)
      --storage-backend <BACKEND>
          Select storage backend (rocksdb or memory) [env: AFS_STORAGE_BACKEND=] [possible values: rocksdb, memory]
      --verbose...
          Increase logging verbosity (repeat for trace level)
      --color <WHEN>
          Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --storage-read-only
          Open the storage backend in read-only mode [env: AFS_STORAGE_READ_ONLY=]
      --storage-cache-size-mb <CACHE_SIZE_MB>
          Override block cache size (per backend) in megabytes
      --storage-write-buffer-mb <WRITE_BUFFER_MB>
          Override write buffer size (applied to all column families) in megabytes
      --trace-id <TRACE_ID>
          Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>
          Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>
          Read auth token from file
      --auth-token-stdin
          Read auth token from stdin
      --server <ADDR>
          Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>
          Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help
          Print help
  -V, --version
          Print version

aether cache clear​

Clear cached blobs and reset derived cache metadata for a session

Usage: aether cache clear [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Render the clear summary as JSON
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether cache inspect​

Inspect cache pressure signals and dirty coverage

Usage: aether cache inspect [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --inode <INODE>           Show dirty ranges and staging metadata for a specific inode
      --json                    Render the cache inspection report as JSON
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether journal​

Inspect and tune journal durability knobs (experimental)

Usage: aether journal [OPTIONS] <COMMAND>

Commands:
  sync        Update journal sync policy or timing parameters
  replay      Replay the journal and scrub orphaned staging state
  throttle    Manually enable or disable journal backpressure throttling
  inspect     Query journal backlog/checkpoint state from a running mount (may be unavailable)
  checkpoint  Request a journal checkpoint from a running mount (may be unavailable)
  dump        Decode a journal entry from a running mount (may be unavailable)
  export      Export journal entries to JSON for offline analysis
  help        Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether journal sync​

Update journal sync policy or timing parameters

Usage: aether journal sync [OPTIONS]

Options:
      --config <FILE>               Path to configuration file (defaults to ./aether.toml when present)
      --policy <POLICY>             Journal sync policy to apply (immediate, manual, interval) [possible values: immediate, manual, interval]
      --interval-ms <MILLISECONDS>  Flush interval in milliseconds when policy=interval
      --quiet                       Suppress routine output (sets log level to error, overrides verbose)
      --backlog-bytes <BYTES>       Flush when pending WAL bytes exceed this threshold (0 disables threshold)
      --verbose...                  Increase logging verbosity (repeat for trace level)
      --color <WHEN>                Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --pid <PID>                   Send SIGHUP to a running aether mount with this PID after updating the configuration
      --json                        Render the tuning outcome as JSON
      --trace-id <TRACE_ID>         Annotate CLI logs with a custom trace identifier
      --yes                         Skip the confirmation prompt and apply the change directly
      --auth-token <TOKEN>          Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>      Read auth token from file
      --auth-token-stdin            Read auth token from stdin
      --server <ADDR>               Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>       Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                        Print help
  -V, --version                     Print version

aether journal replay​

Replay the journal and scrub orphaned staging state

Usage: aether journal replay [OPTIONS]

Options:
      --config <FILE>
          Path to configuration file (defaults to ./aether.toml when present)
      --session-id <SESSION>
          Session identifier used to resolve the journal
      --cache-dir <PATH>
          Base cache directory where journal and staging content reside
      --quiet
          Suppress routine output (sets log level to error, overrides verbose)
      --batch-size <BATCH>
          Replay batch size (0 uses the compiled default)
      --verbose...
          Increase logging verbosity (repeat for trace level)
      --channel-capacity <CAPACITY>
          Replay channel capacity (0 uses the compiled default)
      --color <WHEN>
          Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json
          Enable JSON output when supported by the selected command
      --storage-backend <BACKEND>
          Select storage backend (rocksdb or memory) [env: AFS_STORAGE_BACKEND=] [possible values: rocksdb, memory]
      --storage-read-only
          Open the storage backend in read-only mode [env: AFS_STORAGE_READ_ONLY=]
      --trace-id <TRACE_ID>
          Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>
          Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --storage-cache-size-mb <CACHE_SIZE_MB>
          Override block cache size (per backend) in megabytes
      --auth-token-file <PATH>
          Read auth token from file
      --storage-write-buffer-mb <WRITE_BUFFER_MB>
          Override write buffer size (applied to all column families) in megabytes
      --auth-token-stdin
          Read auth token from stdin
      --server <ADDR>
          Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>
          Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help
          Print help
  -V, --version
          Print version

aether journal throttle​

Manually enable or disable journal backpressure throttling

Usage: aether journal throttle [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --enable                  Enable manual journal throttling (force backpressure)
      --disable                 Disable manual journal throttling
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether journal inspect​

Query journal backlog/checkpoint state from a running mount (may be unavailable)

Usage: aether journal inspect [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Render the inspection output as JSON
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether journal checkpoint​

Request a journal checkpoint from a running mount (may be unavailable)

Usage: aether journal checkpoint [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trim                    After checkpointing, run a trim pass for the acknowledged sequence
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether journal dump​

Decode a journal entry from a running mount (may be unavailable)

Usage: aether journal dump [OPTIONS] --seq <SEQ>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --seq <SEQ>               Journal sequence number to decode
      --json                    Render the decoded entry as JSON
      --raw                     Emit the raw encoded record bytes in base64
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether journal export​

Export journal entries to JSON for offline analysis

Usage: aether journal export [OPTIONS]

Options:
      --config <FILE>
          Path to configuration file (defaults to ./aether.toml when present)
      --session-id <SESSION>
          Session identifier used to resolve the journal
      --cache-dir <PATH>
          Base cache directory where journal and staging content reside
      --quiet
          Suppress routine output (sets log level to error, overrides verbose)
      --output <PATH>
          Output path for exported JSON (default: stdout)
      --verbose...
          Increase logging verbosity (repeat for trace level)
      --color <WHEN>
          Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --start-sequence <SEQUENCE>
          First sequence number to export (inclusive, default 0)
      --end-sequence <SEQUENCE>
          Last sequence number to export (inclusive)
      --json
          Enable JSON output when supported by the selected command
      --limit <COUNT>
          Maximum number of entries to export (0 means no limit)
      --trace-id <TRACE_ID>
          Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>
          Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --pretty
          Pretty-print JSON output (indents entries across multiple lines)
      --auth-token-file <PATH>
          Read auth token from file
      --batch-size <BATCH>
          Replay batch size (0 uses the compiled default)
      --auth-token-stdin
          Read auth token from stdin
      --channel-capacity <CAPACITY>
          Replay channel capacity (0 uses the compiled default)
      --server <ADDR>
          Remote server endpoint for transport/WAL operations
      --storage-backend <BACKEND>
          Select storage backend (rocksdb or memory) [env: AFS_STORAGE_BACKEND=] [possible values: rocksdb, memory]
      --storage-read-only
          Open the storage backend in read-only mode [env: AFS_STORAGE_READ_ONLY=]
      --transport <TRANSPORT>
          Remote transport protocol (grpc or quic) [possible values: grpc, quic]
      --storage-cache-size-mb <CACHE_SIZE_MB>
          Override block cache size (per backend) in megabytes
      --storage-write-buffer-mb <WRITE_BUFFER_MB>
          Override write buffer size (applied to all column families) in megabytes
  -h, --help
          Print help
  -V, --version
          Print version

aether prefetch​

Inspect prefetch activity (experimental)

Usage: aether prefetch [OPTIONS] <COMMAND>

Commands:
  trace  Inspect recent prefetch activity for a mounted session path
  help   Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether prefetch trace​

Inspect recent prefetch activity for a mounted session path

Usage: aether prefetch trace [OPTIONS] --path <PATH>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --path <PATH>             Filesystem path to inspect for recent prefetch activity
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether config​

Inspect or update configuration (experimental)

Usage: aether config [OPTIONS] <COMMAND>

Commands:
  show  Show the resolved configuration
  help  Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether config show​

Show the resolved configuration

Usage: aether config show [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the configuration as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether fallback​

Inspect fallback toggles or flip them (experimental)

Usage: aether fallback [OPTIONS] <COMMAND>

Commands:
  status   Show the current fallback/disable status
  enable   Persistently enable the Aether runtime (clear disable toggle)
  disable  Persistently disable the Aether runtime for fallback
  help     Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether fallback status​

Show the current fallback/disable status

Usage: aether fallback status [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the fallback status as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether fallback enable​

Persistently enable the Aether runtime (clear disable toggle)

Usage: aether fallback enable [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the update outcome as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --yes                     Skip the confirmation prompt and apply the change directly
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether fallback disable​

Persistently disable the Aether runtime for fallback

Usage: aether fallback disable [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the update outcome as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --yes                     Skip the confirmation prompt and apply the change directly
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether metrics​

Inspect metrics configuration (experimental)

Usage: aether metrics [OPTIONS] <COMMAND>

Commands:
  show  Show the configured Prometheus metrics endpoint
  help  Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether metrics show​

Show the configured Prometheus metrics endpoint

Usage: aether metrics show [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the metrics configuration as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether trace​

Capture tracing telemetry (experimental)

Usage: aether trace [OPTIONS] <COMMAND>

Commands:
  capture  Request a temporary trace capture from a running mount
  help     Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether trace capture​

Request a temporary trace capture from a running mount

Usage: aether trace capture [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --duration-secs <SECS>    Duration in seconds to sample traces [default: 10]
      --json                    Enable JSON output when supported by the selected command
      --ratio <RATIO>           Override sampling ratio during capture (0.0-1.0)
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether logs​

Inspect runtime logs

Usage: aether logs [OPTIONS] <COMMAND>

Commands:
  tail  Show recent log output
  help  Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether logs tail​

Show recent log output

Usage: aether logs tail [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --lines <LINES>           Number of log lines to display [default: 200]
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether debug​

Inspect live runtime state (experimental)

Usage: aether debug [OPTIONS] <COMMAND>

Commands:
  handles         Display active handle and inode state for a running mount
  invalidations   Inspect pending invalidations recorded by the mount
  prefetch-trace  Inspect recent prefetch activity for a mounted session path
  help            Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether debug handles​

Display active handle and inode state for a running mount

Usage: aether debug handles [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether debug invalidations​

Inspect pending invalidations recorded by the mount

Usage: aether debug invalidations [OPTIONS] --socket <PATH>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Path to the invalidation debug socket
      --json                    Emit the raw JSON payload instead of the formatted backlog view
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --limit <COUNT>           Maximum number of backlog entries to display in the formatted view (use 0 for all) [default: 20]
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether debug prefetch-trace​

Inspect recent prefetch activity for a mounted session path

Usage: aether debug prefetch-trace [OPTIONS] --path <PATH>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --socket <PATH>           Explicit path to the control socket (overrides cache/session inference)
      --cache-dir <PATH>        Base cache directory where the control socket resides
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --session-id <SESSION>    Session identifier used to derive the default control socket path
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --path <PATH>             Filesystem path to inspect for recent prefetch activity
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether fuse​

Check and clean up FUSE mounts and orphaned processes

Usage: aether fuse [OPTIONS] <COMMAND>

Commands:
  check    Check the health of all Aether FUSE mounts
  cleanup  Clean up stale mounts and orphaned fusermount processes
  help     Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether fuse check​

Check the health of all Aether FUSE mounts

Usage: aether fuse check [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the mount status as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether fuse cleanup​

Clean up stale mounts and orphaned fusermount processes

Usage: aether fuse cleanup [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the cleanup summary as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --yes                     Skip the confirmation prompt and cleanup directly
      --dry-run                 Show what would be cleaned without actually doing it
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether transport​

Inspect and tune remote transport settings

Usage: aether transport [OPTIONS] <COMMAND>

Commands:
  tune    Update a transport tuning parameter
  status  Show the resolved transport configuration
  help    Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether transport tune​

Update a transport tuning parameter

Usage: aether transport tune [OPTIONS] --key <KEY> --value <VALUE>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --key <KEY>               Transport tuning key to update (connection-window-bytes, stream-window-bytes, heartbeat-interval-ms, idle-timeout-ms) [possible values: connection-window-bytes, stream-window-bytes, heartbeat-interval-ms, idle-timeout-ms]
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --value <VALUE>           New value for the selected tuning key
      --json                    Render the tuning outcome as JSON
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --yes                     Skip the confirmation prompt and apply the change directly
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether transport status​

Show the resolved transport configuration

Usage: aether transport status [OPTIONS]

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --json                    Render the transport configuration as JSON
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether wal​

Inspect and replay remote WAL records

Usage: aether wal [OPTIONS] <COMMAND>

Commands:
  list    List WAL records for a session
  status  Summarize WAL record counts for a session
  replay  Replay WAL records to the remote server
  help    Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --json                    Enable JSON output when supported by the selected command
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether wal list​

List WAL records for a session

Usage: aether wal list [OPTIONS] --session-id <SESSION>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --session-id <SESSION>    Session identifier to inspect
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --wal-dir <DIR>           Override the WAL directory for the session
      --status <STATUS>         Filter entries by WAL status [possible values: pending, timed-out, replayed]
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --limit <COUNT>           Limit the number of entries returned
      --json                    Render the WAL entries as JSON
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether wal status​

Summarize WAL record counts for a session

Usage: aether wal status [OPTIONS] --session-id <SESSION>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --session-id <SESSION>    Session identifier to inspect
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --wal-dir <DIR>           Override the WAL directory for the session
      --json                    Render the WAL status as JSON
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version

aether wal replay​

Replay WAL records to the remote server

Usage: aether wal replay [OPTIONS] --session-id <SESSION>

Options:
      --config <FILE>           Path to configuration file (defaults to ./aether.toml when present)
      --session-id <SESSION>    Session identifier to replay
      --quiet                   Suppress routine output (sets log level to error, overrides verbose)
      --wal-dir <DIR>           Override the WAL directory for the session
      --start <START>           Starting mutation id (inclusive) [default: 0]
      --verbose...              Increase logging verbosity (repeat for trace level)
      --color <WHEN>            Control ANSI colour output for logs (auto, always, never) [possible values: auto, always, never]
      --end <END>               Ending mutation id (inclusive) [default: 18446744073709551615]
      --worker-id <WORKER>      Worker identifier to use when replaying entries
      --json                    Render the replay summary as JSON
      --trace-id <TRACE_ID>     Annotate CLI logs with a custom trace identifier
      --auth-token <TOKEN>      Auth token for tenant/admin commands (expected: Bearer <tenant-uuid>:<principal>; falls back to AFS_AUTH_TOKEN)
      --auth-token-file <PATH>  Read auth token from file
      --auth-token-stdin        Read auth token from stdin
      --server <ADDR>           Remote server endpoint for transport/WAL operations
      --transport <TRANSPORT>   Remote transport protocol (grpc or quic) [possible values: grpc, quic]
  -h, --help                    Print help
  -V, --version                 Print version