# Sign in the CLI

Sign the {{cli}} command line in with Touch ID, a security key, Windows Hello or a passkey, or hand it an access key where nobody is at the keyboard.

`dcloud login` opens a CLI session. It acts as you, with your permissions, in one organization, and
ends 12 hours after you signed in. Its access token lasts an hour, and the CLI renews it without
asking, signed by a key that stays on the machine. No access key is stored. Where nobody is at the
keyboard (CI, a container, a scheduled job), give the CLI an access key instead.

On a machine that has a device key to offer (Touch ID on a Mac, a FIDO2 security key on Linux,
Windows Hello on Windows), the first sign-in with a profile creates a key for that profile and you
approve it once in the browser. After that, signing in with the profile is that prompt alone. The
key belongs to the profile: another profile on the same machine enrols its own key. Everywhere
else, every sign-in is approved in the browser.

## Prerequisites

- A console sign-in as a person: a member, or an IAM user with console access. No IAM action is
  needed to sign in; the session can do what your policies allow.
- A passkey on your account (see [Add a passkey](add-a-passkey.md)). Without one you can still
  approve a sign-in while neither your organization nor your own setting requires a passkey, and
  the session is marked unverified.
- For Touch ID: a Mac with a Secure Enclave and the Xcode command line tools
  (`xcode-select --install`).
- For a security key on Linux: a FIDO2 security key plugged in, and libfido2's command line tools
  (the package `fido2-tools` on Debian and Ubuntu, `libfido2` on Fedora).
- For Windows Hello: Windows Hello set up on the PC (a PIN, a face or a fingerprint). The CLI uses
  Windows PowerShell (`powershell.exe`) to reach it.
- Without these, the CLI uses the browser.

## Sign in on a Mac with Touch ID

**CLI**
1. Run the sign-in:

   ```sh
   dcloud auth login
   ```

   The first time with this profile on this Mac, the CLI prints an eight-character code and the
   console's `/activate` address, and opens your browser there. The first time on the Mac, and
   after an update that changes it, it first builds its Touch ID helper (it says this takes about
   20 seconds).

2. In the browser, sign in if asked. The page [Approve a device](/activate) shows
   **Enrol a Mac for Touch ID sign-in** with the **Device**, the **Code** and **Requested from**
   (the address the request came from). Check them.
3. Choose **Approve with passkey** and confirm with your passkey. Choose **Deny** if you did not
   start it.

The page says **Device approved**. The CLI prints the organization, when the session ends, and
where it keeps the session's tokens: the macOS Keychain, or a file only you can read (mode 0600)
when the Keychain refuses them.

Every later `dcloud login` with the same profile on that Mac shows the Touch ID prompt and nothing
else. When the session has ended and you run a command in a terminal, the CLI says the session
expired and asks for Touch ID itself.

## Sign in on Linux with a security key

The CLI uses the first security key that `fido2-token -L` lists. To use another one, set
`DCLOUD_FIDO_DEVICE` to its device path.

**CLI**
1. Run the sign-in:

   ```sh
   dcloud auth login
   ```

   The first time with this profile, the CLI says
   `Touch your security key (…) to create a key for …`. Touch the key, and enter its PIN when
   asked.

2. The CLI prints an eight-character code and the console's `/activate` address, and opens your
   browser there. Sign in if asked. The page shows **Approve a new command line device** with the
   **Device**, the **Code** and **Requested from**. Check them.
3. Choose **Approve with passkey** and confirm with your passkey.

The page says **Device approved**, and the CLI prints the organization and when the session ends.

Every later `dcloud login` with the same profile asks you to touch the security key and enter its
PIN, and nothing else. The key must be plugged in: without it, the CLI stops with
`No security key found` (sign in with `--browser` instead).

A security key without a PIN still works: each time it signs, the CLI says
`This security key has no PIN: a touch signs you in, but cannot confirm sensitive commands.` Such a
touch does not verify you: the session is unverified, sensitive commands are confirmed in the
browser (see [Confirm sensitive CLI commands](confirm-sensitive-cli-commands.md)), and where Touch ID
or a passkey is required, it cannot sign you in. Set a PIN on the key: from then on, each signature
with the PIN verifies you, with no new enrolment, as long as the key was enrolled with a passkey.

## Sign in on Windows with Windows Hello

**CLI**
1. Run the sign-in:

   ```sh
   dcloud auth login
   ```

   The first time with this profile, the CLI says
   `Confirm with Windows Hello to create a key for this PC.` Confirm the Windows Hello prompt.

2. The CLI prints an eight-character code and the console's `/activate` address, and opens your
   browser there. Sign in if asked. The page shows **Approve a new command line device** with the
   **Device**, the **Code** and **Requested from**. Check them.
3. Choose **Approve with passkey** and confirm with your passkey.

The page says **Device approved**, and the CLI prints the organization and when the session ends.

Every later `dcloud login` with the same profile is the Windows Hello prompt, and nothing else. The
key stays in Windows Hello; the CLI stores only its name. When Windows Hello is not set up, the CLI
says `Windows Hello is not set up on this PC; using the browser instead.`

## Sign in in the browser

The CLI uses the browser for every sign-in on a machine without any of the device keys above. To
use the browser where there is one, add `--browser`: it signs in without the device key and enrols
nothing. On a profile that was enrolled, the profile then forgets its device key: the next
`dcloud login` without `--browser` enrols the device again with a new key, and the old one stays
listed on your account until you remove it (see [End CLI sessions](end-cli-sessions.md)). On Linux
and Windows, setting `DCLOUD_DEVICE_KEY=none` keeps the CLI from enrolling the security key or
Windows Hello; a profile already enrolled still signs in with it.

**CLI**
1. Run the sign-in:

   ```sh
   dcloud auth login --browser
   ```

   The CLI prints an eight-character code and the console's `/activate` address, and tries to open
   your browser there. On a machine without a browser, open the address on any device.

2. Sign in if asked. When the browser opened from the CLI, the code is already looked up. Otherwise
   enter the code under **Enter the code shown in your terminal** and choose **Continue**.
3. The page shows **Sign in the command line** with the **Device**, the **Code** and
   **Requested from**. Choose **Approve with passkey** and confirm with your passkey.

The page says **Signed in**, and the CLI prints the organization and when the session ends. It keeps
the tokens in the macOS Keychain, or the desktop keyring on Linux where there is one, otherwise in
a file only you can read (mode 0600).

Without a passkey on your account, the button is **Approve**, and the session is marked unverified.
With a passkey that is not at hand, choose
**My passkey is not at hand: approve without it (the session is marked unverified)**. Neither is
offered when your organization or your own setting requires a passkey: the page says
`Your organization or your account requires a passkey here, and your account has none yet.`

A device enrolled without a passkey signs in with its prompt, but its sessions are unverified and
its prompt does not count as a confirmation: sensitive commands are confirmed in the browser, which
needs a passkey. Add a passkey, then enrol the device again with `dcloud logout --forget-device`
and `dcloud login`.

## Choose the organization and the profile

```sh
dcloud auth login --org orders-team --profile orders
```

Replace orders-team with an organization's id or slug and orders with a profile
name. On an enrolled device, `--org` picks the organization the session opens in; without it, the
session opens in the organization you joined first. In the browser, enrolling a device included,
the session opens in the organization the console has open when you approve, whatever `--org`
says. Without `--profile`, the profile is named after `--org`, or `default`.

## Sign in with an access key

Where nobody can approve a sign-in, create a key in the console (see
[Create an access key](create-an-access-key.md)), preferably for a service account, and either
store it in a profile:

```sh
dcloud auth login --with-key
```

which asks for `<key id>:<secret>` without echoing it, or set it in the environment and store
nothing on disk:

```sh
export DCLOUD_ACCESS_KEY='EWS1EXAMPLEEXAMPLE00:<secret>'
```

`--key <value>` or `--stdin` pass the key without a prompt. The CLI checks the key against the API
before saving it, unless you add `--no-verify`. Your organization can refuse people's own access
keys, but never a service account's (see
[Require Touch ID or a passkey for the CLI](require-touch-id-for-the-cli.md)).

## Work with profiles

```sh
dcloud auth whoami          # identity, organization, credential; for a session, when it ends and when you last confirmed
dcloud auth list            # stored profiles; * marks the current one
dcloud auth use staging     # make another profile the current one
```

For a script or an SDK, `dcloud auth token` prints your session's current access token, renewed
first only when it has less than a minute left: it is valid for at most an hour, and possibly for
little more than a minute. Send it as `Authorization: Bearer <token>`.

```sh
export TOKEN="$(dcloud auth token)"
```

## If the sign-in fails

- The CLI says `The code expired before it was approved`: run `dcloud login` again and approve
  within 10 minutes.
- The CLI says `The request was denied in the browser`: someone chose **Deny**.
- The page says `That code is not valid, or it has expired. Codes last 10 minutes.`: the code is
  mistyped, older than 10 minutes, or was approved or denied already.
- The CLI says the device is no longer enrolled: its key was removed (see
  [End CLI sessions](end-cli-sessions.md)), and the CLI enrols it again in the browser.
- The CLI says
  `An administrator of … blocked this device for the organization. Sign in another way, or ask them to unblock it.`
  (403, code `DEVICE_KEY_BLOCKED`): an administrator blocked this device in the organization (see
  [Manage a member's CLI devices](manage-a-members-cli-devices.md)). Sign in with `--browser`
  (the profile then forgets the device's key), or ask them to unblock it. The device still signs in
  to your other organizations.
- 403 `Your organization requires Touch ID or a passkey to sign in to the CLI.` (or
  `Your account requires …` when your own setting is
  **Always, and only sign in with one of those or a passkey**): the device's key does not count as
  verifying you, because it was enrolled without a passkey, is a software key, or is a security key
  that signed without a PIN. For a key enrolled without a passkey, add a passkey and enrol the
  device again; for a security key without a PIN, set a PIN on it.
- 403 `This CLI session was opened without Touch ID or a passkey, and your organization now requires one. …`
  (or `… and your account now requires one. …`): run `dcloud login` again, with your device key or
  a passkey.
- 401 `This security key was refused: its signature counter went backwards (a copied key?).`: the
  key's signature counter did not grow since its last use, which is what a copied key does.
- The approval page says
  `This version of … signs in with a 90-day access key, which your organization or your account no longer allows. …`,
  and the CLI reports the request as denied: an older CLI. Run `dcloud upgrade`.
- `dcloud auth login --with-key` says `The API rejected that access key`: the key is mistyped,
  inactive, expired or refused by your organization.

## Related

- [Confirm sensitive CLI commands](confirm-sensitive-cli-commands.md)
- [End CLI sessions](end-cli-sessions.md)
- [Manage a member's CLI devices](manage-a-members-cli-devices.md)
- [Require Touch ID or a passkey for the CLI](require-touch-id-for-the-cli.md)
- [Create an access key](create-an-access-key.md)
