CLI Authentication

Install the Hamster CLI on its own and connect it to your account through browser sign-in, with a callback URL fallback when a local browser cannot open.

Overview

Most people install the Hamster plugin instead: it installs the hamster binary for you. Install the CLI on its own when you want that binary in your terminal. Start at Install Hamster for the plugin path.

The Hamster CLI is a command-line tool called hamster. It connects to your Hamster account and lets you sync the plan to disk, view Tasks, switch Brief context, and manage work from the terminal.

Authentication uses a browser-based login flow — the CLI opens your browser, you sign in with your existing Hamster credentials, and the session is transferred back to your terminal automatically. If the terminal cannot open a local browser, you can finish sign-in in any browser and paste the full callback URL into the terminal.

How It Works

Install the CLI:
```
curl -fsSL https://tryhamster.com/cli/install | bash
```
The installer puts the hamster binary in $HOME/.hamster/bin and adds that directory to PATH. It does not open a browser or sign you in.
Run hamster auth login. The CLI opens your default browser to a Hamster sign-in page. A banner on the page confirms that you are signing in to authorize your CLI. Sign in with your Hamster email and password, or with any social provider your account already uses.
After you sign in, Hamster creates an independent CLI session — separate from your browser session — and sends it back to the terminal. If you have multi-factor authentication enabled on your account, you will be prompted to complete that step before the session is issued.
Inside the repository you want to connect, run hamster init. The CLI creates .hamster/, lets you select a team, runs the first sync, and generates the agent skill file. Run hamster sync --watch to keep that context up to date as your team works.

Browserless Sign-In

Use the callback URL flow when a local browser cannot open:

hamster auth login --no-browser

Open the printed authorization URL in any browser and finish signing in. When the browser returns a callback URL, paste the full URL into the terminal to complete sign-in.

Key Capabilities

Browser-based OAuth 2.1: The default flow opens your browser for sign-in and returns the session to the terminal. You do not need to copy tokens or credentials manually. The CLI uses OAuth 2.1 with PKCE for secure token exchange.
Browserless sign-in: If hamster auth login cannot open a local browser, copy the authorization URL into any browser and finish signing in. When the browser returns a callback URL, paste the full URL into the terminal to complete sign-in.
Credential storage: Credentials live in your OS keychain by default, and fall back to ~/.hamster/auth.json with user-only permissions on machines without one, so you only need to sign in again if you sign out or the session expires.
Environment variable auth: For CI/CD pipelines, containers, and sandboxed environments, you can authenticate by setting environment variables instead of using the browser flow:
- HAMSTER_ACCESS_TOKEN — Provide a valid access token directly
- HAMSTER_REFRESH_TOKEN — Provide a refresh token; the CLI exchanges it for an access token automatically
- When environment variables are set, the CLI skips the browser flow entirely.
Independent CLI session: The session stored on your machine is separate from your browser session. Logging out of Hamster in the browser does not affect your CLI session.
MFA support: If your account has multi-factor authentication enabled, the browser-based flow handles the MFA step before issuing the CLI session. The CLI also prompts for MFA in the terminal when required.
Team switching: Run hamster team list to see available teams, hamster team switch to select the active team, and hamster team members to inspect its membership.
Auto-update: The CLI checks for updates automatically and shows a progress indicator when downloading a new version. Updates are verified with a checksum before installing.

Tips

Run hamster auth login at any time to re-authenticate or switch accounts.
Use hamster team switch to select the active team when you belong to multiple workspaces.
If hamster auth login cannot open a local browser, copy the authorization URL into any browser, finish signing in, and paste the full callback URL into the terminal.
To select or switch Briefs, run hamster sync <brief-id-or-url>.
The CLI session persists across terminal sessions. You only need to authenticate once unless you sign out or your session expires.
Set HAMSTER_ACCESS_TOKEN in your CI/CD environment to use the CLI in automated pipelines without interactive login.