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.

Last updated 19 November 2026View as Markdown

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

  1. Run the sign-in:

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

  1. Run the sign-in:

    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), 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

  1. Run the sign-in:

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

  1. Run the sign-in:

    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

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), preferably for a service account, and either store it in a profile:

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:

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

Work with profiles

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

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), 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). 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.
Did this page help you?