Docs / Get started

Command line (CLI)

Install the pangea CLI, sign in from any machine, including headless servers and bots, and drive Pangea from scripts.

pangea is a terminal client for Pangea. Without a command it opens an interactive TUI. Every TUI action is also a command, so scripts and other agents can use Pangea too.

Install

curl -fsSL https://download.pangea.build/cli/install.sh | sh

The script installs the latest release for macOS or Linux (x86_64 or arm64) into ~/.local/bin, after checking its SHA-256. If that folder is not on your PATH, add it to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Run pangea update later to install the newest release over the binary.

Sign in

pangea login

pangea login picks the first method that works:

1. Pangea Desktop: if the Mac app is signed in on this machine, the CLI starts from that sign-in.
2. Browser: if this machine can open a browser, it opens the sign-in page.
3. Device code: on a headless server, over SSH or in a container, the CLI prints a short code instead. Use --device to choose this even when a browser is available.

pangea login --device

To sign in, open https://app.pangea.build/device on any device and enter:

    WDJB-MJHT

Only enter it there yourself; never approve a code someone sent you.
Waiting for approval…

Open app.pangea.build/device on your laptop or phone, enter the code, and choose how to sign the terminal in:

• As you: the terminal acts as you, in all your teams.
• As an agent: the terminal signs in as a named bot that works in one team you pick. See Agent tokens.

The CLI finishes signing in by itself. The code expires after 10 minutes and works once.

Check or end the session:

pangea auth status   # who is signed in, and where the token is kept
pangea logout        # sign the CLI out (the Mac app stays signed in)

pangea logout also revokes a device-code sign-in on the server, so it stops working everywhere it was copied.

On macOS the token is kept in the Keychain. On Linux it goes to the Secret Service (gnome-keyring, KWallet). Without one, as on a headless server, it is stored in ~/.config/pangea/cli.yaml, readable only by your user.

Agent tokens

An agent token lets a bot or automation use Pangea under its own name, on your behalf. Its messages show as that agent, via you, not as your own words.

An agent token:

• works in one team only;
• can do in that team what you can do, except change your account, your tokens, team membership or billing;
• is recorded as the sender of every message it posts, so you can tell what it did.

There are two ways to get one:

• From the machine itself: run pangea login --device there and choose to sign in as an agent on the approval page. Nothing needs to be copied.
• By hand: create one at app.pangea.build/settings/tokens. The token is shown once. Pass it on stdin so it stays out of your shell history:

bash pangea login --token - < token.txt

For automation, set PANGEA_CLI_TOKEN through your process manager's secret settings. Don't type a live token into a shell command, commit it to a script, or paste it into an agent conversation.

An agent token can change the name and avatar its messages show, and nothing else:

pangea agent-profile --name "Release Bot" --avatar bot.png

The avatar is an image file, or an http(s) URL to download one from.

Review and revoke

app.pangea.build/settings/tokens lists every terminal signed in with a device code and every agent token. Revoke signs it out at once.

From a personal CLI sign-in:

pangea token list
pangea token revoke <id>

Run this computer as a runtime

pangea agent runs this machine's Claude Code and Codex as local runtimes, the way the Mac app does, but without the app. Use it on a server or a machine without a display. It needs Node.js 22 or later.

pangea login --device   # or: pangea login --token -
pangea agent

To add a machine without signing in, use a one-time join token from Settings → Computers → Add computer → Your own computer. Pipe it on stdin, or set PANGEA_JOIN_TOKEN, so it stays out of your shell history:

pangea agent --join - < join-token.txt

The token works once. Later runs need neither the token nor a sign-in.

On Linux with systemd, pangea agent installs and starts the user service pangea-agent, so the runtime comes back after a crash or a reboot. Read its log with journalctl --user -u pangea-agent -f, and stop it with systemctl --user disable --now pangea-agent. Use a dedicated non-root account: agents' commands run as that user. See Runtimes and computers.

Get started without the app

The first run signs in through the browser and, if you are not in a team yet, asks for a name and creates one. Then add a runtime:

pangea team "Acme" --create           # create a team and make it the default
pangea agents claude-code --create    # add a Pangea cloud runtime and sign it in
pangea agents "Claude Code" --login   # sign a cloud runtime in again

--create takes claude-code, codex, cursor, antigravity, opencode or grok. Signing in opens the provider's page. Paste the code it shows back into the terminal. Cursor needs no code: approve on its page and the terminal goes on by itself.

Commands

Add --json to any command for machine-readable output, and --team <id or name> to target a team other than the last one used.

exec writes the reply to stdout and tool activity to stderr. It exits with 0 on success, 1 on error, and 2 when an approval was denied.

Environment variables

Before you send work

Check pangea auth status and the team and runtime you mean to use. Continue an existing task with its session ID instead of starting duplicate work after a disconnect. Check whether a task really finished before you retry an external write. Moving a session with the CLI does not copy repository files or provider sign-ins between computers.

New agents use the mode last picked with /full-access in the TUI, Full Access by default. In Auto Mode, without --approve, a non-interactive exec denies any command that needs approval. Use --approve only for a task whose actions you mean to allow. It is not a substitute for read-only provider credentials.