# Get started with the Airdress CLI

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

## Sign in

```sh
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:

```sh
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:

```sh
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.

```sh
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](/cli/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`:

   ```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.

```sh
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](/functions/): put code behind your airdress.
- [Shells](/shells/): a terminal on one of your machines.
- [Claude Code](/editor/claude-code/): the same reach from an editor, over MCP.
- [Devices, machines and homes](/cli/devices-and-machines/): what is attached
  to your airdress, and how it got there.
- [Scripting](/cli/scripting/): JSON output and exit codes for automation.