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). 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-toolson Debian and Ubuntu,libfido2on 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
Run the sign-in:
dcloud auth loginThe first time with this profile on this Mac, the CLI prints an eight-character code and the console's
/activateaddress, 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).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.
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.
Run the sign-in:
dcloud auth loginThe 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.The CLI prints an eight-character code and the console's
/activateaddress, 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.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
Run the sign-in:
dcloud auth loginThe first time with this profile, the CLI says
Confirm with Windows Hello to create a key for this PC.Confirm the Windows Hello prompt.The CLI prints an eight-character code and the console's
/activateaddress, 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.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.
Run the sign-in:
dcloud auth login --browserThe CLI prints an eight-character code and the console's
/activateaddress, and tries to open your browser there. On a machine without a browser, open the address on any device.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.
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 ordersReplace 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-keywhich 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 oneFor 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: rundcloud loginagain 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, codeDEVICE_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.(orYour 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. …): rundcloud loginagain, 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. Rundcloud upgrade. dcloud auth login --with-keysaysThe API rejected that access key: the key is mistyped, inactive, expired or refused by your organization.