Skip to main content

Ship Aether CLI to end users

This guide is for teams that want end users to work locally through Aether CLI while the hosted product continues to manage sessions and workflow state.

What you are actually shipping​

You are not shipping the server.

You are shipping:

  • a local client experience
  • a mount workflow
  • endpoint and auth setup
  • user support guidance
  • a product flow that knows when local mounts should be used

The basic rollout model​

The strongest rollout model is:

  1. your product creates or selects a session
  2. the user receives a session ID or a direct launch path
  3. Aether CLI mounts that session locally
  4. the product still handles review, approval, and persistence

This keeps the local editing experience and the hosted workflow control clearly separated.

What users need from you​

An end user usually needs:

  • how to install aether
  • which endpoint to use
  • what auth context is required
  • how to mount a session
  • what to do when it fails

Your minimum rollout package​

1. Installation guidance​

Users need a clear way to get the aether binary.

2. Endpoint guidance​

Users need one obvious setting path:

  • AFS_AETHER_SERVER_ENDPOINT
  • or [bridge].server_endpoint

3. Mount guidance​

Users need one or two copy-pasteable examples to mount a session.

4. Troubleshooting guidance​

Users need to know:

  • use aether doctor
  • use aether status --session-id ... after the runtime is active
  • use logs and metrics only when diagnosis is needed

Product integration guidance​

Do not make users discover sessions manually if your product already knows which session they should open.

Good product flows:

  • deep-link into a “mount this session” action
  • show the session ID explicitly
  • show whether the session is review-ready, pending approval, or otherwise constrained

Support guidance​

When users report a problem, support should gather:

  • endpoint in use
  • relevant environment overrides
  • aether version
  • aether doctor
  • any useful aether logs tail or aether status --session-id ... output

Cache guidance for rollout​

Advise users to:

  • keep cache roots explicit if they use multiple environments
  • separate personal and automation/cache-heavy workflows

This avoids confusing cross-environment state.

When not to push Aether CLI​

Do not force Aether CLI into workflows that only need:

  • session creation
  • approvals
  • reporting
  • source creation and promotion

If the user does not need local filesystem semantics, the HTTP/API product flow is probably enough.

What success looks like​

A successful Aether CLI rollout means:

  • users can mount quickly
  • users understand endpoint and auth setup
  • support issues are diagnosable
  • your product still owns workflow state cleanly