Skip to content
Polaris
Esc
↑↓navigate↵open⌘Jpreview
On this page

Polaris CLI

Install the Polaris CLI on your computer to list your Sessions, continue one locally and manage variables.

The Polaris CLI runs in a terminal on your own computer. Use it to find your Sessions, copy a Session to your computer to keep working on it there, and manage your Project’s variables from a .env file. It runs on macOS and Linux, on x64 and arm64 processors. Windows isn’t supported.

The polaris command on a Machine is a different tool with its own commands; see Machine commands.

Install

curl -fsSL https://plrs.sh/install.sh | sh

The installer checks the download and puts polaris in ~/.local/bin. If it says Add ~/.local/bin to PATH., add that folder to your shell’s PATH. Then check that it works:

polaris version

Sign in

polaris auth login

The CLI shows a code and opens Polaris in your browser. Check that the page shows the same code, then choose Connect. To sign in as someone else, choose Switch account first.

  • When no browser opens, for example over SSH, open the link the CLI prints.
  • Press Esc to cancel. If the code expires, press Enter for a new one.
  • If you belong to more than one organization, the CLI asks which one to use and remembers your choice.

The CLI keeps your sign-in in the macOS Keychain or the Linux kernel keyring, never in a file. On Linux, the keyring empties when the computer restarts, so sign in again after a restart.

Command What it does
polaris auth status Shows which account you’re signed in as.
polaris auth logout Signs out and removes the saved sign-in from this computer.
polaris config set organization Chooses your default organization from a list. Add an organization ID to set it directly.
polaris config show Shows your current settings.
polaris config unset organization Clears the default, so the CLI asks again.

List your Sessions

polaris sessions

This lists the 30 Sessions you own that were most recently active. Narrow the list with these options:

Option Shows
--search <text> Sessions whose title, Project or Machine matches.
--status <status> Sessions with that status: idle, active, waiting, failed or completed. Repeat it for more than one.
--project <project id> Sessions in one Project.
--scope org Every Session you can see in the organization, not only yours.
--archived Archived Sessions only. --include-archived shows both.
--limit <1-100> Up to that many Sessions. Pass the cursor the CLI prints to --cursor for the next page.

Add --output json to get each Session’s ID and link for a script.

Continue a Session on your computer

You can copy a Codex Session to your computer, with its files and the agent’s conversation, and resume it in Codex there.

  1. In the Session, open Session actions (⋯) and choose Continue locally….
  2. On Give to your agent, choose Copy prompt and paste it into a coding agent on your computer. It installs the CLI if needed, helps you sign in in your browser, copies the Session and shows you the command that resumes it. To do it yourself, choose Manual and copy the command.

From a terminal, pass the Session’s link or ID. --to chooses the new folder:

polaris sessions pull <Session link or ID> --to <new folder>

The CLI copies the Session into a new folder and prints the command that opens it in Codex. It doesn’t start Codex for you, and the Session stays in Polaris.

  • The CLI never overwrites a folder or a Codex conversation that already exists. Choose a new folder.
  • If the agent is still working, the CLI asks whether to copy now, wait or cancel.
  • You need Codex installed on your computer to resume.

Manage environment variables

polaris env changes a Project’s environment variables from your computer, for example to import a .env file. It never prints a value.

Command What it does
polaris env list --project <id> Lists the Project’s variables and where each comes from, without values.
polaris env import <file> --project <id> Previews a .env file, then imports it after you confirm. Use - to read from standard input.
polaris env history --project <id> Shows who added, replaced, shared or removed each variable, and when.
polaris env remove <name> --project <id> Removes a variable from the Project.
polaris env share <name> --scope <organization|personal> --project <id> Shares one of your Organization or Personal variables with a Project. --scope names where the variable comes from. polaris env unshare takes the same flags and stops sharing it.
  • Imported values are Secrets. Add --config to import them as Config.
  • A name that already exists is skipped. Add --replace <name> to replace it, or --skip <name> to leave out a name from the file.
  • For your Organization or Personal library instead of a Project, use --scope organization or --scope personal.
  • Without a terminal, or when the file comes from standard input, the CLI only previews. Add --yes to apply the change.

Update

polaris update

The CLI doesn’t update itself in the background. Run polaris update to get the latest version, and polaris version to see which one you have.

Options for every command

Option What it does
--org <organization id> Uses this organization instead of your default.
--output json Prints the result as JSON for scripts. JSON output never asks a question.
--profile <name> Keeps a separate sign-in, for example for a second account.
--help Shows a command’s options.

To set up tab completion, run polaris completion --help and follow the steps for your shell.

If it doesn’t work

  • Secure credential storage is unavailable on this machine.: unlock the macOS Keychain or turn on the Linux kernel keyring, then run polaris auth login again. polaris doctor checks it.
  • Run: polaris auth login: your sign-in expired or was removed. Sign in again.
  • This Polaris binary is not managed by the official installer.: reinstall with the install command above, then polaris update works.
  • Choose an organization with –org.: you’re in more than one organization and have no default. Run polaris config set organization, or add --org.

Was this page helpful?