Sign In & Login

Clonit Cloud is an optional extension that adds team collaboration, cross-device snapshot access, and sharing. Before you can use any cloud feature, you sign in with clonit login — a browser-based login that needs no password and no API key typed into your terminal.

How sign-in works

clonit login runs an OAuth 2.0 Device Authorization Grant (RFC 8628) against the central auth service. The flow is designed for command-line tools:

1. Clonit asks the auth service for a short, one-time user code and a verification URL.
2. Clonit prints the code and URL, and (unless you pass --no-browser) opens the URL in your browser.
3. You sign in and approve the request in the browser — including any SSO or single sign-on your organization uses.
4. Clonit polls in the background and, once you approve, stores the resulting session locally.

Identity is owned entirely by the auth service. Clonit never sees or stores your password, and it runs no sign-in flow of its own — it simply hands you off to the auth service and receives a session back.

Note

Clonit auto-discovers the auth service and OAuth client for you. The only thing you must configure is cloud.url — the address of your Clonit Cloud. Clonit fetches the auth service details from the cloud automatically.

Prerequisites

You only need cloud.url set in your config before signing in:

~/.config/clonit/config.yaml

cloud:
  url: "https://cloud.clonit.ai"

You can set this with clonit config edit. See Connect Your Agent for the full cloud setup, and Configuration for the complete config reference.

Sign in

clonit login

Clonit prints a short code and a verification URL, opens the URL in your browser, and waits for you to approve. Once approved, you are signed in and the session is stored locally.

Signing in over SSH or in a headless shell

If you are on a remote machine with no browser, pass --no-browser. Clonit prints the verification URL and code instead of trying to open a browser — open the URL on any device, enter the code, and approve:

clonit login --no-browser

Tip

The verification URL and code work from any device. You can run clonit login --no-browser on a server and complete the approval from your laptop or phone.

Check who you are

clonit whoami

This shows the currently signed-in identity and validates that the stored session is still good. Use it to confirm you are signed in (and to which account) before running cloud operations.

Sign out

clonit logout

This clears the stored session. After signing out you will need to run clonit login again before using cloud features.

A typical login lifecycle

clonit login            # print a code + URL, open the browser, approve
clonit whoami           # confirm the current login and validate the session
clonit logout           # clear the stored session when you're done

Where your session is stored

Your session — the access and refresh tokens that prove you are signed in — is stored in:

~/.config/clonit/credentials.json

This file is created with 0600 permissions (readable and writable only by you) and is kept separate from config.yaml. Clonit refreshes the session automatically as it expires, so you stay signed in across commands without re-running clonit login each time.

Caution

Treat credentials.json like any other secret. Anyone who can read it can act as you against Clonit Cloud. To revoke access on a machine, run clonit logout, which clears the file.

Login flags

Flag	Description
--no-browser	Print the verification URL and code instead of opening a browser. Use this over SSH or on headless machines.
--auth-url	Override the auth service URL instead of discovering it from the cloud. Useful for an air-gapped or self-hosted auth service.
--client-id	Override the OAuth client_id instead of discovering it from the cloud.
--scope	Request an optional OAuth scope.

You normally need none of these — clonit login discovers everything from cloud.url. The --auth-url and --client-id overrides exist for self-hosted or air-gapped deployments where you want to pin those values explicitly.

Humans vs. automation

clonit login is for people. The browser-based device grant is the right choice for interactive use on your own machine.

Note

For CI/CD pipelines and other headless automation, use a Clonit Cloud API key (cloud.api_key) instead of interactive login. API keys are designed for unattended automation and do not require a browser. See Connect Your Agent for API key setup.

Troubleshooting

• “cloud.url is not set” — Sign-in needs to know which cloud to talk to. Set cloud.url with clonit config edit, then try again.
• The browser didn’t open — Run clonit login --no-browser and open the printed URL yourself, or copy it to another device.
• The code expired before you approved — User codes are short-lived for security. Just run clonit login again to get a fresh code.
• clonit whoami says you’re not signed in — Your session may have been cleared or expired beyond refresh. Run clonit login again.

See Also

• login command — Full flag reference for clonit login
• logout command — Reference for clonit logout
• whoami command — Reference for clonit whoami
• Connect Your Agent — Cloud setup, agent registration, and API keys
• Cloud Storage — Push and pull snapshots with cloud-managed storage
• Configuration — Full config reference, including the cloud block