> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Phaseo CLI

> Install the official Phaseo CLI, configure coding harnesses, and manage Phaseo from the terminal.

The Phaseo CLI is distributed as `@phaseo/cli`. It connects coding harnesses to Phaseo and provides a first-party terminal workflow for the Phaseo control plane.

Use it when you want to:

* sign in as a real Phaseo user from a local shell, remote shell, or agent runtime
* create and rotate API keys or management keys
* manage workspaces, presets, settings, and guardrails
* use first-party CLI OAuth while user-owned OAuth apps remain in private testing
* inspect models, providers, pricing, credits, activity, analytics, and generations

## Install

```bash title="npm" theme={null}
npm install -g @phaseo/cli
```

```bash title="pnpm" theme={null}
pnpm add -g @phaseo/cli
```

```bash title="yarn" theme={null}
yarn global add @phaseo/cli
```

```bash title="bun" theme={null}
bun add -g @phaseo/cli
```

## Check the installed version

```bash theme={null}
phaseo --version
phaseo version
phaseo version --json
```

* `phaseo --version` prints the installed version.
* `phaseo version` prints the version plus the recommended update command for the current package manager.
* interactive runs also show an update hint when a newer published version is available.

The older `phaseo` command remains available as a compatibility alias.

## Sign in

Start with:

```bash theme={null}
phaseo login
```

The CLI supports two first-party flows:

* **Sign in with Phaseo**: browser OAuth with authorization code + PKCE
* **Sign in with Device Code**: best for SSH, CI, headless shells, and agent environments

You can force either path:

```bash theme={null}
phaseo login --browser
phaseo login --device-code
```

Remote and non-interactive environments automatically prefer device code.

## Terminal output

Interactive terminals receive Phaseo's colour, hierarchy, and ephemeral setup spinners. Spinners use `stderr` and clear their line when work completes. Non-TTY `stderr` and `TERM=dumb` disable animation; `NO_COLOR` disables colour. Commands using `--json` always return decoration-free structured output for agents and automation. Use `FORCE_COLOR=1` only when a terminal wrapper supports colour but does not report itself as a TTY.

## Confirm who you are

```bash theme={null}
phaseo whoami
phaseo whoami --json
```

This returns your current Phaseo user, scopes, active workspace, and available workspaces.

## Create keys

```bash theme={null}
phaseo keys create --name "Local CLI Key"
phaseo keys create --name "Agent Sandbox Key" --json
phaseo keys current
```

Use `--json` when an agent or automation needs the raw created key once.

## Manage workspaces and guardrails

```bash theme={null}
phaseo workspaces list
phaseo workspaces members <workspace-id-or-slug>

phaseo guardrails list
phaseo guardrails create --name "Production Safety" --body-json '{"enabled":true}'
```

The CLI covers the Phaseo dashboard's management tasks from the terminal, including billing, budgets, BYOK, routing and identity. See [Manage Phaseo from an agent](https://phaseo.app/docs/v1/developers/manage-from-an-agent.md) for a command for each task.

## Launch supported coding harnesses

Persistent integrations use the product name directly:

```bash theme={null}
phaseo codex
phaseo claude-code
phaseo deepseek-harness
phaseo opencode
phaseo pi
phaseo prime-agent
phaseo openclaw
phaseo aider
phaseo roo-code
phaseo kilo-code
phaseo continue
phaseo cursor
phaseo zed
```

Use `--model`, `--catalog all|default`, or `--dry-run` as needed. The older `phaseo integrations setup <integration>` form remains available for compatibility, but is not required.

The CLI can launch Cline, Kilo Code, oh-my-pi, Muse Code, and MiniMax Code with temporary provider configuration and a dedicated Phaseo key. Each harness has its own integration guide with setup and troubleshooting details: [Cline](https://phaseo.app/docs/v1/guides/integrations/cline.md), [Kilo Code](https://phaseo.app/docs/v1/guides/integrations/kilo-code.md), [oh-my-pi](https://phaseo.app/docs/v1/guides/integrations/oh-my-pi.md), [Muse Code](https://phaseo.app/docs/v1/guides/integrations/muse-code.md), and [MiniMax Code](https://phaseo.app/docs/v1/guides/integrations/minimax-code.md).

```bash theme={null}
phaseo cline --model openai/gpt-5.6-terra -- --tui
phaseo kilo --model openai/gpt-5.6-terra --
phaseo omp --model openai/gpt-5.6-terra --
phaseo muse --model meta/muse-spark-1.3 --
phaseo minimax --model openai/gpt-5.6-terra --
```

Use `phaseo run <cline|kilo|omp|muse|minimax>` for the explicit form. Phaseo flags come before `--`; harness flags come after it. Use `--catalog all` to sync all active Phaseo text/chat models, or preview without creating a credential with:

```bash theme={null}
phaseo cline --model openai/gpt-5.6-terra --dry-run --json
```

Missing Cline, Kilo Code, and oh-my-pi installations are offered interactively. Muse Code and MiniMax Code use their official installers when the command is missing. On Windows, MiniMax Code uses its official PowerShell installer; use `--skip-install` when you manage either harness separately. The launchers do not overwrite existing Cline, Kilo, oh-my-pi, Muse Code, or MiniMax Code configuration.

## OAuth apps

Phaseo uses one OAuth authorization server for the first-party CLI, user-created applications, and dynamically registered MCP clients. The CLI uses browser or device login with rotating refresh tokens. Third-party clients use authorization code with PKCE, explicit scopes and workspace consent, revocable delegated access tokens, and optional protected-resource binding.

The hosted Phaseo API enables third-party OAuth. Self-hosted or preview API deployments keep it disabled unless `PHASEO_THIRD_PARTY_OAUTH_ENABLED` is set to a truthy value. Accepted truthy values are `1`, `true`, `yes`, and `on`, matched case-insensitively after trimming whitespace. Enabling it exposes user-created OAuth app management and dynamic client registration, so pair it with reviewed redirect URI, consent, client-secret, rate-limit, and workspace authorization configuration.

```bash title=".env" theme={null}
PHASEO_THIRD_PARTY_OAUTH_ENABLED=true
```

```bash title="Docker" theme={null}
docker run -e PHASEO_THIRD_PARTY_OAUTH_ENABLED=true phaseo
```

```yaml title="Kubernetes" theme={null}
env:
  - name: PHASEO_THIRD_PARTY_OAUTH_ENABLED
    value: "true"
```

## Security model

* CLI sessions require OS-backed secure storage by default. Set `PHASEO_SESSION_BACKEND=file` only as an explicit opt-in when an OS credential store is unavailable; it stores refresh tokens in a permission-restricted plaintext file.
* `phaseo logout` revokes the stored refresh token before clearing local state.
* Management keys require explicit capabilities.
* Regular inference keys rely on guardrails, routing policies, and workspace settings rather than a separate scope model.

## Update

```bash title="npm" theme={null}
npm install -g @phaseo/cli@latest
```

```bash title="pnpm" theme={null}
pnpm add -g @phaseo/cli@latest
```

```bash title="yarn" theme={null}
yarn global add @phaseo/cli@latest
```

```bash title="bun" theme={null}
bun add -g @phaseo/cli@latest
```

## Next steps

* [Management API keys](https://phaseo.app/docs/v1/developers/management-api-keys.md)
* [Authentication](https://phaseo.app/docs/v1/developers/authentication.md)
* [Codex](https://phaseo.app/docs/v1/guides/integrations/codex.md)
* [Claude Code](https://phaseo.app/docs/v1/guides/integrations/claude-code.md)
* [Cline](https://phaseo.app/docs/v1/guides/integrations/cline.md)
* [Kilo Code](https://phaseo.app/docs/v1/guides/integrations/kilo-code.md)
* [oh-my-pi](https://phaseo.app/docs/v1/guides/integrations/oh-my-pi.md)
* [Muse Code](https://phaseo.app/docs/v1/guides/integrations/muse-code.md)
* [MiniMax Code](https://phaseo.app/docs/v1/guides/integrations/minimax-code.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.