Skip to main content

Automation patterns

This page goes deeper than the basic automation page.

Use it when you are designing repeatable non-interactive Aether CLI usage rather than a one-off local shell session.

Pattern: environment-specific wrappers​

Create one wrapper per environment and make the endpoint and cache root explicit.

Example:

#!/usr/bin/env bash
set -euo pipefail

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

exec aether "$@"

This avoids accidental cross-environment reuse of cache or credentials.

Pattern: CI mount worker​

Use Aether CLI in CI only when the job actually needs local filesystem semantics.

Good fit:

  • a toolchain that expects local paths
  • a step that needs a mounted workspace
  • an environment where local editors are not involved, but filesystem semantics still matter

Poor fit:

  • pure control-plane workflows that only create sessions or request approvals

Pattern: ephemeral automation runtime​

When using Aether CLI in automation:

  • keep cache roots explicit
  • keep logs structured
  • keep the runtime lifetime bounded to the job
  • stop the local runtime when the job finishes

This keeps later incident captures deterministic and reduces stale local-state leakage between runs.

Pattern: support wrapper​

Use a support-oriented wrapper when diagnosing user issues:

  • set debug logs temporarily
  • enable metrics on a local address
  • record aether --version, the resolved endpoint/cache root, and aether doctor, aether logs tail, and aether metrics show

This creates a repeatable support capture workflow without making those settings the permanent default.

Pattern: mixed product plus local mount workflow​

This is one of the strongest real-world patterns:

  1. create or select sessions over HTTP
  2. hand a session ID to a local user
  3. mount with Aether CLI
  4. keep approvals, annotations, and persistence in the HTTP/API layer

This pattern keeps Aether CLI focused on local filesystem use and keeps workflow control in the product or service layer.

Pattern: per-job cache isolation​

If jobs are short-lived or untrusted relative to one another, isolate cache roots per job.

Use this when:

  • jobs run in CI
  • jobs should not share local cache assumptions
  • cleanup must be deterministic

Pattern: persistent workstation defaults plus temporary overrides​

Use config for:

  • stable personal defaults
  • endpoint you use every day
  • preferred logging format

Use env vars for:

  • temporary debugging
  • one-off environment changes
  • wrapper-controlled behavior

Pattern: automation with local metrics​

Enable metrics only when a consumer exists.

If a runner or support tool will scrape them, bind a local address explicitly. If not, avoid turning metrics into permanent ambient complexity.

Pattern: freshness-sensitive automation​

If automation must observe remote changes quickly, tune:

  • AFS_AETHER_LOOKUP_TTL_SECS
  • AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS
  • AFS_AETHER_DIR_CACHE_TTL_SECS

Do this only for workflows where freshness is the actual requirement.

Automation anti-patterns​

Avoid:

  • sharing one ambiguous cache root across all environments
  • using Aether CLI where the HTTP API alone is enough
  • keeping debug logging permanently enabled
  • assuming aether status is a full preflight validation tool

For a new automation flow, make these explicit:

  1. endpoint
  2. auth context
  3. cache root
  4. logging format
  5. whether metrics are needed
  6. whether the job really needs a local mount

If you cannot answer those clearly, the automation story is not ready yet.

See also: