fallow cloud

Connect your machine to Fallow Cloud without copying an API key. Fallow cloud login runs the device flow and stores a read-only key in the OS keychain.

Use fallow cloud login to give the CLI a Fallow Cloud key on your machine. You do not copy or paste a key. The CLI shows a code, you approve it in the dashboard, and Fallow Cloud creates a read-only API key for you, your organization and this machine.

fallow cloud login
fallow cloud logout

Log in

Open https://fallow.cloud/device and enter the code ABCD-EFGH
This creates a read-only API key for "build-box". Waiting for approval...
Logged in. Stored the read-only key fallow_read_k1_ab... in the OS keychain.

Open the URL and sign in to the dashboard.
Make sure that the code is the same as the code in your terminal.
Approve the request. The dashboard shows the machine name of the key.

Only an organization owner can approve a key. When a member approves the code, Fallow Cloud signs the member in but creates no key. The CLI then prints the reason from Fallow Cloud, stores nothing, and exits with code 2. Ask an owner to approve the code.

The key starts with fallow_read_k1_. It can read production data, for example for fallow inspect --cloud, but it cannot upload or change data. The key shows in Settings > API keys with the name fallow cloud login (<machine name>). Revoke it there like any other key.

Flag	Description
`--machine-name <NAME>`	Name of this machine on the key. Default: the host name.
`--api-url <URL>`	Fallow Cloud API base URL. Default: `$FALLOW_API_URL`, else `https://api.fallow.cloud`.

Only a person can approve a login. A coding agent must not run fallow cloud login for you.

Where the key goes

The CLI stores the key in the OS keychain, with the service fallow-cloud and the API base URL as the account:

OS	Store
macOS	The login keychain, through `security`.
Linux	The Secret Service (for example GNOME Keyring), through `secret-tool`, when a desktop session runs.
Other, or no keychain	The file `~/.config/fallow/credentials` (or `$XDG_CONFIG_HOME/fallow/credentials`), with mode 0600 on Unix.

The CLI never prints the key.

Key order

Every fallow command that reads production data from Fallow Cloud uses the same order. This includes the cloud tools of the fallow MCP server, which run these commands:

--api-key, when the command has this flag.
$FALLOW_API_KEY.
The key in the OS keychain.
The key in the credentials file.

$FALLOW_API_KEY always wins over the stored key, so CI keeps the key that you set on the runner.

Upload commands (fallow coverage upload-inventory, upload-static-findings, upload-source-maps) and fallow coverage setup --cloud --wait need a live key. They read only --api-key and $FALLOW_API_KEY, because the stored key is read-only and Fallow Cloud refuses it for these routes.

Variable	Description
`FALLOW_CREDENTIAL_STORE=file`	Use the credentials file, not the keychain.
`FALLOW_CREDENTIAL_STORE=none`	Do not read or write a stored key, for example on a shared runner.

Log out

fallow cloud logout removes the stored key from the keychain and from the credentials file. The key stays valid in Fallow Cloud until you revoke it in Settings > API keys.

Flag	Description
`--api-url <URL>`	API base URL of the key to remove. Default: `$FALLOW_API_URL`, else `https://api.fallow.cloud`.