---
title: Polaris CLI
description: 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](/docs/machine-commands).

## Install

```bash
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:

```bash
polaris version
```

## Sign in

```bash
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 <kbd>Esc</kbd> to cancel. If the code expires, press <kbd>Enter</kbd>
  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

```bash
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:

```bash
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](/docs/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

```bash
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`.