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

# Pascal CLI

> Reference for the pascal command: run the local editor, download and verify its runtime, connect MCP clients, claim hosted agents, and script it with JSON output and exit codes.

The `pascal` command comes from the `@pascal-app/cli` package. It runs the open-source
Pascal editor on your machine, connects MCP clients to your local projects, and lets a
hosted autonomous agent link itself to the person accountable for it. This page is the
command reference. For a walkthrough of the first run, Docker self-hosting and local
agents, see [Run Pascal locally](/docs/developers/local-editor).

## Install

You need [Node.js](https://nodejs.org/en/download) 22.13 or newer, with npm. Run the CLI
without installing it:

```bash theme={null}
npx @pascal-app/cli editor
```

An interactive `npx` first run installs the same version globally once the editor is
healthy, so the shorter `pascal` command works afterwards. To install it yourself:

```bash theme={null}
npm install --global @pascal-app/cli
pascal --version
```

Without a global install, prefix any command on this page with `npx @pascal-app/cli`.

## Commands

### Run the editor

| Command | What it does |
| - | - |
| `pascal editor [--foreground] [--no-open] [--port <n>] [--runtime <path>]` | Install the web runtime if needed, make sure the editor and MCP service are running, and open the editor in your browser. |
| `pascal start [--foreground] [--port <n>] [--runtime <path>]` | The same, without opening a browser. |
| `pascal stop [--force]` | Stop the managed editor and MCP processes. `--force` is a guarded recovery path for an unhealthy process. |
| `pascal restart` | Restart the editor and MCP service. This is how a running editor switches to the runtime a newer CLI ships. |
| `pascal status [--json]` | Report editor and MCP health, version, URL, ports and process details. |
| `pascal logs [--follow] [--lines <n>]` | Print the last lines of the editor log (100 by default), or keep following it with `--follow` (`-f`). |

`--port` asks for a specific loopback port. If it's taken, Pascal says so and picks a
free one. Without it, the operating system assigns a free port. `--foreground` keeps the
editor attached to the terminal; the command then exits with the editor's exit code.

### Open projects

| Command | What it does |
| - | - |
| `pascal open [project]` | Start Pascal if needed, then open the editor, or the project you name by ID, unique ID prefix or unique name. |
| `pascal resume [project]` | Open your most recently edited project, or the one you name. |
| `pascal projects [--json]` | List local projects, starting Pascal if needed. |
| `pascal project list [--json]` | Same as `pascal projects`. |
| `pascal project open <id-or-name>` | Same as `pascal open <project>`. |
| `pascal project resume [id-or-name]` | Same as `pascal resume [project]`. |

`open`, `resume`, `projects` and the `project` commands also accept `--runtime <path>`,
used when they have to start the editor.

### Update and diagnose

| Command | What it does |
| - | - |
| `pascal update [--version <version>] [--runtime <path>]` | Install the runtime for the latest or an exact published CLI version, health-check it, and activate it. If the check fails, the previous runtime comes back. |
| `pascal doctor [--json]` | Check Node.js, storage, the runtime, process health and plugin state. |
| `pascal info [--json]` | Print the CLI and Node.js versions, resolved paths, runtime, editor, MCP and plugin state. |
| `pascal --version` | Print the CLI version. |
| `pascal --help` | Print usage. `pascal mcp --help` and `pascal agent --help` explain those groups. |

`--version` takes an exact version such as `1.0.5`, or `latest`. `--runtime` applies
when the target is the version you're running. `update` doesn't touch
your projects or a globally installed `pascal` command. Update the command itself with
`npm install --global @pascal-app/cli@latest`.

### Connect MCP clients

| Command | What it does |
| - | - |
| `pascal mcp connect` | The stdio connector MCP clients run. It starts the MCP service if needed and finds its current port. |
| `pascal mcp status [--json]` | Report whether the MCP service is running and healthy, and its port. |
| `pascal mcp config [--json]` | Print the JSON entry for `mcp.json` clients. |
| `pascal mcp setup <codex\|claude>` | Add the connector to Codex or Claude Code. It never overwrites an existing Pascal entry. |

`pascal mcp connect` uses the MCP service in the npm package, so it works on a machine
that has never downloaded the web runtime. `pascal mcp setup` needs the global `pascal`
command at the same version as the CLI you run it with. See
[Local MCP with the Pascal CLI](/docs/developers/mcp#local-mcp-with-the-pascal-cli) for
client setup.

### Claim a hosted agent

| Command | What it does |
| - | - |
| `pascal agent claim [--no-open] [--json]` | Request a 15-minute claim code for an autonomous agent and open the claim page. |
| `pascal agent status [--json]` | Check that the agent's key is active and report its agent ID, mode, claim state and organization scope. |

Both commands read the agent's hosted Pascal API key from `PASCAL_API_KEY`, send it to
Pascal, and never store or print it. `--no-open` or `--json` skips opening the browser.
A new claim supersedes the agent's previous code. These commands don't upload or link
local projects. See
[Agent accounts and workspace invitations](/docs/developers/mcp#agent-accounts-and-workspace-invitations).

```bash theme={null}
PASCAL_API_KEY='sk_live_...' pascal agent claim --no-open
PASCAL_API_KEY='sk_live_...' pascal agent status --json
```

### Plugins

| Command | What it does |
| - | - |
| `pascal plugin list [--json]` | Show the managed-plugin lock. It's empty in this release. |

The CLI doesn't install plugins yet: any other `plugin` subcommand fails with
`plugin_command_unavailable`. See [Create a plugin](/docs/developers/plugins).

## The web editor runtime

The npm package holds only the CLI and the MCP service. The web editor itself is a
separate archive per CLI version, `pascal-web-runtime-<version>.tar.gz`, attached to
the matching [GitHub release](https://github.com/pascalorg/editor/releases). Each CLI
version pins its runtime by URL, size and SHA-256 digest.

### First start

The first command that starts the editor (`editor`, `start`, `open`, `resume`,
`projects`, the `project` commands, or `update`) downloads the archive into
`~/.pascal/tmp` and shows its progress. Then it:

1. Checks the archive against the SHA-256 digest published inside the npm package. On
   a mismatch it deletes the download and installs nothing (`runtime_digest_mismatch`).
2. Extracts it and installs it into `~/.pascal/runtime/<version>`.
3. Starts the editor on it.

Later starts reuse the installed runtime. Two first runs at once share one download. If
the installed runtime is damaged, the next start downloads and verifies it again; your
projects in `~/.pascal/data` are separate and untouched.

After you upgrade the CLI, a running editor keeps its older runtime. `pascal editor`
warns you, and `pascal restart` or `pascal update` switches to the runtime the new CLI
pins.

### Offline and air-gapped machines

Download the archive for your CLI version on a connected machine, copy it over, and
pass it with `--runtime`:

```bash theme={null}
# On a connected machine. Use the version that pascal --version prints.
curl --fail --location --remote-name \
  "https://github.com/pascalorg/editor/releases/download/@pascal-app/cli@1.0.5/pascal-web-runtime-1.0.5.tar.gz"

# On the offline machine
pascal editor --runtime ./pascal-web-runtime-1.0.5.tar.gz
```

An archive passed with `--runtime` goes through the same digest check as a download, so
it must be the archive for the CLI version you're running. `--runtime` also accepts an
extracted runtime directory, which is installed as it is, without a digest check; use it
for a runtime you built yourself from the
[editor repository](https://github.com/pascalorg/editor).

When a download fails, the error (`runtime_download_failed`) prints the archive URL, its
expected digest and the `--runtime` command to run once you've copied the file.

### Proxies

Downloads go through `HTTPS_PROXY` (or `ALL_PROXY`), including a proxy with basic
authentication, and skip hosts listed in `NO_PROXY`. Only `https://` archive URLs are
accepted.

## Script the CLI

### JSON output

Commands that take `--json` print one JSON document on stdout instead of text, for
example:

```bash theme={null}
pascal status --json
pascal projects --json
pascal doctor --json
```

On `editor` and `start`, `--json` also skips the automatic global install; add
`--no-open` to `editor` to keep the browser closed. `pascal logs` and
`pascal mcp connect` don't take `--json`.

### Errors

Without `--json`, an error prints `Error: <message>` on stderr. With `--json`, it prints
one line of JSON on stderr:

```json theme={null}
{"error":"unknown_command","message":"Unknown command: architect","details":{"command":"architect"}}
```

`error` is a stable code to branch on, `message` is for people, and `details` appears
only when there's more to say, such as the HTTP `status` of a hosted request.

### Exit codes

| Exit code | Meaning |
| - | - |
| `0` | Success. |
| `1` | The command failed: a runtime download, a hosted request, a failing `doctor` check, or a process that's running but unhealthy in `status`. |
| `2` | Invalid usage: an unknown command or option, or a malformed value such as a non-integer `--port`. |

With `--foreground`, `pascal editor` and `pascal start` exit with the editor process's
own code.

### Common error codes

| Code | What to do |
| - | - |
| `unknown_command`, `invalid_option` | Check the command against `pascal --help` (exit `2`). |
| `invalid_version` | Pass an exact version such as `1.0.5`, or `latest`, to `pascal update --version` (exit `2`). |
| `runtime_download_failed` | Retry, or fetch the printed archive URL elsewhere and pass it with `--runtime`. |
| `runtime_digest_mismatch` | The archive isn't the one this CLI version pins. Download it again for your exact CLI version. |
| `runtime_source_missing` | The `--runtime` path doesn't exist. |
| `npm_unavailable`, `update_failed` | `pascal update --version` installs the other release with npm. Make sure npm works, then retry. |
| `pascal_command_unavailable` | Run `npm install --global @pascal-app/cli@<version>` with the version the error names, then repeat `pascal mcp setup`. |
| `mcp_client_unavailable`, `mcp_setup_failed` | The client isn't on your `PATH`, or it already has a Pascal entry. |
| `agent_api_key_missing` | Set `PASCAL_API_KEY` to the agent's key. |
| `agent_claim_unauthorized`, `agent_status_unauthorized` | The key is invalid or revoked. |
| `agent_claim_forbidden` | Only an autonomous agent's key can start a claim. |
| `agent_already_claimed` | The agent already has an accountable person. Check it with `pascal agent status`. |
| `agent_claim_rate_limited` | Too many claim attempts. Wait, then try again. |
| `plugin_command_unavailable` | Plugin installation isn't in this release (exit `2`). |

## Environment variables

| Variable | Effect |
| - | - |
| `PASCAL_HOME` | Where Pascal keeps runtimes, projects, logs and process state. Default `~/.pascal`. Use separate directories for independent local instances. |
| `PASCAL_API_KEY` | The hosted agent key for `pascal agent claim` and `pascal agent status`. Processes the CLI starts don't inherit it. |
| `PASCAL_BUNDLED_RUNTIME_DIR` | An extracted runtime directory to use instead of downloading. `--runtime` takes precedence. |
| `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | Proxy settings for the runtime download. |

## Related

* [Run Pascal locally](/docs/developers/local-editor): first run, files on disk, updates and Docker
* [Connect an AI agent](/docs/developers/mcp): local and hosted MCP
* [Pascal API (v1)](/docs/developers/api): call the hosted Architect from your own code


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