Pascal CLI

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.

Install

You need Node.js 22.13 or newer, with npm. Run the CLI without installing it:

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:

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

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.

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. 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:

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).
Extracts it and installs it into ~/.pascal/runtime/<version>.
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:

# 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. 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:

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:

{"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.

Run Pascal locally: first run, files on disk, updates and Docker
Connect an AI agent: local and hosted MCP
Pascal API (v1): call the hosted Architect from your own code

Integrate

Extend Pascal

Install

Commands

Run the editor

Open projects

Update and diagnose

Connect MCP clients

Claim a hosted agent

Plugins

The web editor runtime

First start

Offline and air-gapped machines

Proxies

Script the CLI

JSON output

Errors

Exit codes

Common error codes

Environment variables

​Install

​Commands

​Run the editor

​Open projects

​Update and diagnose

​Connect MCP clients

​Claim a hosted agent

​Plugins

​The web editor runtime

​First start

​Offline and air-gapped machines

​Proxies

​Script the CLI

​JSON output

​Errors

​Exit codes

​Common error codes

​Environment variables

​Related

Install

Commands

Run the editor

Open projects

Update and diagnose

Connect MCP clients

Claim a hosted agent

Plugins

The web editor runtime

First start

Offline and air-gapped machines

Proxies

Script the CLI

JSON output

Errors

Exit codes

Common error codes

Environment variables

Related