Skip to main content

Common workflows

Workflow: mount a session and work locally​

  1. Obtain the session ID.
  2. Set AFS_AETHER_SERVER_ENDPOINT or [bridge].server_endpoint.
  3. Mount the session locally.
  4. Use your editor, shell, or tooling against the mounted path.
  5. Use API or product workflows for checkpoints, approvals, or persistence as needed.

Workflow: switch between environments​

When switching between staging, beta, or production-style environments:

  • Keep endpoint selection explicit.
  • Use shell wrappers or per-environment config files.
  • Avoid reusing ambiguous cache locations unless that is intentional.

A safe shell pattern is:

export AFS_AETHER_SERVER_ENDPOINT='https://grpc.aetherfs.io'
export AFS_AETHER_CACHE_DIR="$HOME/.cache/aether-prod"

Workflow: enable debug output for an issue​

When a mount or connectivity problem occurs:

export AFS_AETHER_LOG='debug'
export AFS_AETHER_LOG_FORMAT='text'
aether doctor

If another system will parse the output, prefer JSON logs instead.

Then rerun the actual mount command with explicit --session-id and --mount-dir, because doctor only covers local preflight checks.

Workflow: inspect runtime state after starting Aether CLI​

Use commands such as:

aether status --session-id '<session-id>'
aether metrics show
aether logs tail

Remember that aether status is most useful when the local Aether CLI runtime is already active.

Workflow: isolate automation from your personal cache​

For scripts or CI:

export AFS_AETHER_CACHE_DIR="$HOME/.cache/aether-ci"
export AFS_AETHER_CACHE_SHARED_ROOT="$HOME/.cache/aether-ci-shared"

That keeps automation state separate from your day-to-day workstation cache.

Workflow: tune metadata freshness​

If your workflow needs fresh remote visibility, reduce TTL-related settings:

  • AFS_AETHER_LOOKUP_TTL_SECS
  • AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS
  • AFS_AETHER_DIR_CACHE_TTL_SECS

If your workflow prioritizes fewer round trips, increase them carefully.

Workflow: hand off to API-driven persistence​

A common pattern is:

  1. Use Aether CLI for local editing.
  2. Use the HTTP API or your product workflow for annotations, approvals, checkpoints, and commits.
  3. Stop the local runtime when the interactive phase is complete.

This keeps local filesystem work and durable workflow control cleanly separated.