Get started with the Airdress CLI

Install the CLI first (Install), then sign in. Everything else follows from which airdress a command acts on.

Sign in

airdress auth login

Your browser opens on the account picker. Every login asks which account, so a second profile never silently inherits the one the browser is already signed in to. When it is done, the CLI prints which account the profile got.

On a machine without a browser, use the device flow and finish the sign-in elsewhere:

airdress auth login --device      # prints a URL and a code
airdress auth login --no-browser  # the same, and never tries to open one

Note

The device-flow page cannot show an account picker: it signs in whichever account that browser already uses. Open the link in a private window when you want a different one.

Check and end a sign-in:

airdress auth status              # a read; it never refreshes or writes
airdress auth logout              # ends the session at the identity provider, then forgets the tokens

auth status says authenticated while a refresh token is on file, even if the access token beside it has lapsed; it renews on next use. expired means a browser login is really needed.

Profiles: one account on one hub

The default hub is https://account.airdress.co; the default profile is created on your first login.

airdress auth login --profile work          # a second account, side by side
airdress profile create staging --endpoint https://staging.example.com
airdress profile use work                   # make it the active one
airdress use work                           # the same, shorter
airdress profile list
airdress profile show                       # the active profile, credentials redacted

Most commands take --profile <name> (or -p) to act as another profile once. Where profiles and tokens are kept is in Keys and storage.

Which airdress a command acts on

Most commands act on a current airdress, resolved in this order, highest first:

1. --airdress <name> or -A <name> on the command line. A name, an id or the full address all work.

2. AIRDRESS_NAME in the environment.

3. A .airdress file in the working directory or a parent, holding the name. Off by default; opt in once in ~/.airdress/preferences.toml:

   [discovery]
   directory_marker = true

4. The airdress pinned on the active profile, set with airdress airdress use <name> or the short airdress a use <name>. The pin is checked against the hub when set, and clears itself if the airdress later disappears.

With none of these, the command stops and points you at airdress airdress list.

When the airdress came from the environment, a marker or the pin, the CLI says so on stderr: → acting on home (source: profile-default). Silence it with --quiet or AIRDRESS_QUIET=1. Under --output json it is always silent, and the resolved airdress travels inside the JSON instead.

airdress airdress list              # the airdresses you own
airdress a use home                 # pin one
airdress airdress probe             # how the hub reaches it: direct or relayed
airdress -A office airdress probe   # one command on another
airdress current                    # "work / home (source: profile-default)"

airdress current --output json is built for shell prompts.

Where to next

• Functions: put code behind your airdress.
• Shells: a terminal on one of your machines.
• Claude Code: the same reach from an editor, over MCP.
• Devices, machines and homes: what is attached to your airdress, and how it got there.
• Scripting: JSON output and exit codes for automation.