CLI Authentication

The Reoclo CLI authenticates via OAuth device flow — your browser handles the login, and the CLI stores tokens locally. There are no API keys to generate, paste, or rotate for interactive use.

Logging in

reoclo login

The CLI prints a short device code and opens your browser to the Reoclo dashboard. Approve the request in the dashboard’s Connect IDE modal. Once approved, the CLI confirms authentication and stores tokens in your OS keyring (or ~/.reoclo/config.json on headless systems).

Confirm it worked:

reoclo whoami

Non-TTY environments

If the CLI is running without an interactive terminal (e.g., inside a container or CI job), it exits with:

OAuth device flow requires an interactive terminal. Use an Automation Key for CI/CD — see https://docs.reoclo.com/guides/api-keys/

CI/CD pipelines should use Automation Keys (rca_*) instead of the device flow.

Logging out

reoclo logout

Removes stored tokens for the active profile. Credentials are deleted from the keyring (or config file) immediately.

To log out a specific profile:

reoclo logout --profile staging

Multiple profiles

Use --profile to maintain credentials for more than one tenant or environment simultaneously:

reoclo login --profile staging --api https://api.staging.reoclo.com
reoclo login --profile prod

Switch the active profile:

reoclo profile use staging
reoclo whoami   # confirms the active profile

Or override for a single command without changing the default:

reoclo servers ls --profile prod

Set REOCLO_PROFILE in your shell to change the default without running reoclo profile use:

export REOCLO_PROFILE=staging
reoclo whoami   # uses the staging profile

Working across organizations

A single login can be granted access to several organizations. To work in more than one at the same time — different orgs in different project directories — you don’t switch a global “active org”. Instead, bind each directory to an org so commands run there automatically target it.

The quickest way is reoclo init, which writes a .reoclo file for you. You can also create it by hand in a project root:

{ "org": "acme" }

Every reoclo command run anywhere in that directory tree now targets acme. A second project with { "org": "globex" } runs against globex at the same time — no waiting, no global switch. Commit .reoclo so teammates inherit the org.

Precedence

The organization a command targets is resolved in this order (first match wins):

Source	Scope
`--org <slug>` flag	one command
`REOCLO_ORG` environment variable	one shell
`.reoclo` file (nearest ancestor of the working directory)	one project tree
the profile’s own org (`reoclo org use`)	global default

So an explicit --org or REOCLO_ORG always wins for a one-off, while .reoclo overrides the global default for everything in that project.

# Per command, regardless of directory:
reoclo servers ls --org globex

# Per shell:
export REOCLO_ORG=globex

# See the org (and where it came from) for the current directory:
reoclo org current

Org overrides require an OAuth login (reoclo login); under an automation key a committed .reoclo is ignored, so it never affects CI. The org must be one you authorized — switch your global default any time with reoclo org use <slug>, or list what’s available with reoclo org ls.

Binding a profile (and custom backends)

.reoclo can also pin a profile for the directory, which is the right tool when a project needs a different account or a different backend (staging, self-hosted, dev):

{ "profile": "staging", "org": "acme" }

The profile is resolved with the same precedence as the org — --profile flag → REOCLO_PROFILE → .reoclo profile → the active profile — and is likewise ignored under an automation key. If the named profile doesn’t exist locally, the command fails loudly telling you to reoclo login --profile <name> rather than silently using the wrong account.

Because a profile carries its own API URL (set when you ran reoclo login --profile staging --api https://api.staging.reoclo.com), binding a profile is how you point a project at a non-default backend — safely, since the target comes from your own login rather than the committed file. For that reason .reoclo intentionally does not accept a raw api field: a committed file that could redirect where your token is sent would be a credential-leak vector. Use --api / REOCLO_API_URL for an explicit one-off, or a bound profile for a durable per-project backend.

Credential storage

By default the CLI stores tokens in the OS keyring:

Platform	Backend
macOS	Keychain
Linux	Secret Service (libsecret / gnome-keyring)
Windows	Credential Manager

On headless Linux servers without dbus the keyring is unavailable. The CLI automatically falls back to a 0600-mode file at ~/.reoclo/config.json.

Force file storage

reoclo login --no-keyring

Stores credentials in ~/.reoclo/config.json even when a keyring is available. Useful when keyring prompts are disruptive (e.g., on a shared workstation where dbus asks for a password on each session).

Require keyring storage

reoclo login --keyring

Fails with an error if no keyring backend is available, rather than falling back to file storage. Use this when you want a hard guarantee that credentials are not written to disk.

Check which backend is in use:

reoclo keyring status

Migrate an existing file-based credential into the keyring:

reoclo keyring migrate

Token refresh

OAuth access tokens expire and are refreshed automatically in the background before they lapse. No manual re-login is needed under normal operation.

If the refresh fails — for example, if consent was revoked from the dashboard — the next CLI command exits with:

Session expired. Run `reoclo login` to re-authenticate.

Run reoclo login again to start a fresh device flow.

Troubleshooting

Browser did not open

Some environments block automatic browser launching. The CLI also prints the device approval URL to the terminal — copy and open it manually:

Open this URL in your browser to approve the request:
https://app.reoclo.com/device?code=XXXX-XXXX

Port already in use

The device flow does not require an inbound port. If you see a port conflict, it is from another process unrelated to reoclo login.

If reoclo whoami still shows an error after reoclo login completes, try:

reoclo logout
reoclo login

This clears any stale credential entry before writing the new one.

Command exits immediately with “no TTY”

You are running in a non-interactive shell. Use an Automation Key for unattended access.

reoclo login — command reference
reoclo logout — remove stored credentials
reoclo whoami — show the active identity
reoclo profile — manage named profiles
reoclo keyring — inspect or migrate stored tokens
Automation Keys — for CI/CD and unattended access