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, lets a hosted autonomous agent link itself to the person accountable for it, hands briefs to the hosted Architect, and deploys static viewers to Pascal hosting. 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`, `pascal agent --help`, `pascal architect --help` and `pascal viewer --help` explain those groups.

--version takes an exact version such as 1.0.6, 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

Run the hosted Architect

These commands need @pascal-app/cli 1.0.6 or newer. They hand a brief to the Architect, Pascal’s building model, which designs in one of your hosted projects while you follow the run, detach from it, check on it or cancel it. They’re a thin client over the Pascal API Responses endpoint: every run starts in background mode, so it runs on Pascal, not on your machine.

Command	What it does
`pascal architect run "<brief>" --project <id> [--effort <level>] [--max-credits <n>] [--detach] [--json]`	Start a run and stream the Architect’s reply.
`pascal architect status <id> [--json]`	Show a run’s status, details and output so far.
`pascal architect cancel <id> [--json]`	Cancel a queued or running run.

You need:

A Pascal API key in PASCAL_API_KEY: one you created in Settings, or an autonomous agent’s key. Its user or organization must be able to edit the project. The CLI sends it to Pascal and never stores or prints it. Without it, every architect command fails with agent_api_key_missing.
A hosted project id for --project. The Architect always works in an existing project; a run without one is rejected with architect_invalid_request.
Pascal credits. Each run spends credits, like a turn in the editor’s chat. See Credits.

Start a run

export PASCAL_API_KEY='sk_live_...'
pascal architect run "A two-storey, three-bedroom house with an open-plan kitchen" \
  --project project_your_project_id

The Architect’s reply streams to stdout as it’s written. Progress lines, including the run’s ID and a summary when it ends, go to stderr, so you can redirect the reply:

pascal architect run "A small studio with a mezzanine" \
  --project project_your_project_id > design.md

Press Ctrl+C to detach. The run keeps going on Pascal, and the CLI prints the status and cancel commands for it.

Option	Effect
`--project <id>`	The hosted project the run works in.
`--effort low\|medium\|high\|pro`	Use the `architect-<effort>` model. Without it, the run uses `architect`.
`--max-credits <n>`	The most credits the run may spend, a positive integer. See Cap the credits a turn spends.
`--detach`	Queue the run, print its ID and return without streaming.
`--json`	Print the run as one JSON object when it ends, instead of streaming text. With `--detach`, print it as soon as the run is queued.

Run in the background

--detach returns as soon as Pascal accepts the run:

pascal architect run "A single-storey office for 12 people" \
  --project project_your_project_id --effort high --detach

Architect run resp_abc123 is queued on architect-high.
Follow it: pascal architect status resp_abc123
Cancel it: pascal architect cancel resp_abc123

Check or cancel a run

pascal architect status resp_abc123
pascal architect cancel resp_abc123

status prints the run’s ID, status, model, project, credit cap, creation time and any error, then the output so far. cancel prints the same details without the output. A run that already ended comes back as it ended. Only the person who started a run can cancel it. With --json, run, status and cancel all print the run in this shape:

{
  "schemaVersion": 1,
  "id": "resp_abc123",
  "status": "completed",
  "model": "architect-high",
  "projectId": "project_your_project_id",
  "maxCredits": 50,
  "createdAt": "2026-10-23T12:00:00.000Z",
  "outputText": "...",
  "error": null
}

status is one of queued, in_progress, completed, failed, cancelled or incomplete; text output writes in_progress as in progress. projectId, maxCredits, createdAt and outputText are null when there’s nothing to report. error is null, or an object with a code and a message, either of which can be null. A run that ends incomplete carries its reason as the message, for example max_credits when it reached its credit cap.

Deploy a hosted viewer

This command ships in the next @pascal-app/cli release after 1.1.1. It uploads a static build of your viewer to Pascal hosting and makes it live at the address Pascal assigned when you registered the viewer, such as https://misty-cove-4tg7.pascal-viewer.app. It’s a thin client over the viewer hosting endpoints.

Command	What it does
`pascal viewer deploy <dir> --viewer <id> [--dry-run] [--json]`	Check a build directory against the hosting limits, upload it and activate it.

You need:

A hosted viewer. Register it under Settings → Viewers → Host on Pascal and pass its ID to --viewer. The CLI doesn’t create viewers.
A Pascal API key in PASCAL_API_KEY that can manage the viewer’s workspace. The CLI sends it to Pascal and never stores or prints it. --dry-run doesn’t need it.

npm run build
pascal viewer deploy ./dist --viewer viewer_your_viewer_id --dry-run
PASCAL_API_KEY='sk_live_...' pascal viewer deploy ./dist --viewer viewer_your_viewer_id

Pass the build output directory, with index.html at its top. Hidden files, folders and symlinks, such as .DS_Store, are skipped and listed, except a top-level .well-known/. Any other symlink stops the deploy before anything uploads. So do files with an invalid path or an extension that isn’t on the hosting allowlist; the error lists up to 10 of those so you can fix the build in one pass. Limits are 2,000 files, 100 MiB in total and 25 MiB per file.

Option	Effect
`--viewer <id>`	The hosted viewer to deploy to. Required.
`--dry-run`	Check the build and print what would upload, without a key or network.
`--json`	Print the result as one JSON object, without progress.

Deployed 57 files (6.9 MiB) to viewer_abc123.
Deployment: viewerdeploy_def456
Live at: https://misty-cove-4tg7.pascal-viewer.app/
Skipped 1 hidden entry: .DS_Store

The CLI uploads 8 files at a time. Each file gets a deadline that grows with its size, and all uploads must finish within the 15-minute upload window. On a terminal, progress goes to stderr; in CI and other non-interactive shells, nothing is printed there unless the deploy fails. A deploy that fails partway leaves the previous build live. Run the command again and it starts a fresh deployment. Every attempt counts toward the limit of 30 deployments per viewer per hour. With --json:

{
  "schemaVersion": 1,
  "viewerId": "viewer_abc123",
  "deploymentId": "viewerdeploy_def456",
  "status": "active",
  "fileCount": 57,
  "totalBytes": 7235174,
  "skipped": [".DS_Store"],
  "url": "https://misty-cove-4tg7.pascal-viewer.app/"
}

url is the live address. It’s null only against an older Pascal server that doesn’t return one. A dry run prints schemaVersion, "dryRun": true, fileCount, totalBytes, skipped, and files with each file’s path, size, sha256 and contentType.

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.6/pascal-web-runtime-1.0.6.tar.gz"

# On the offline machine
pascal editor --runtime ./pascal-web-runtime-1.0.6.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: deploy","details":{"command":"deploy"}}

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 and the error code Pascal answered with:

{"error":"architect_unauthorized","message":"PASCAL_API_KEY is invalid or revoked. Check it with \"pascal agent status\".","details":{"status":401,"code":"invalid_api_key"}}

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`.
`75`	`pascal architect` and `pascal viewer deploy` only: Pascal can’t take the request right now. Retry the same command later.
`130`	`pascal architect run` only: you detached with Ctrl+C. A run Pascal had confirmed keeps going.

With --foreground, pascal editor and pascal start exit with the editor process’s own code. pascal architect run exits 0 only when the run ends completed, and 1 when it ends failed, cancelled or incomplete.

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.6`, 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, or for `pascal viewer deploy`, to a key that can manage the viewer’s workspace.
`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`).
`architect_executor_unavailable`	No Architect is free, so no run started. Retry in a few minutes (exit `75`).
`architect_rate_limited`, `architect_unavailable`	Too many requests, or the Architect is briefly down. Wait, then retry (exit `75`).
`architect_unauthorized`, `architect_forbidden`	The key is invalid, revoked or not allowed to use the Architect. Check it with `pascal agent status`.
`architect_insufficient_credits`	The account behind the key doesn’t have enough credits for the run.
`architect_invalid_request`	Pascal rejected the request, for example a run without `--project`. `details.code` holds the API’s error code.
`architect_run_not_found`	No run with that ID is visible to this key, or you’re cancelling a run someone else started.
`architect_failed`	Any other HTTP error, such as a project the key can’t edit; `details` holds its `status` and `code`.
`architect_stream_interrupted`, `architect_run_error`	Following the run failed. A run that has an ID keeps going; check it with `pascal architect status <id>`.
`architect_unreachable`, `architect_timeout`	Pascal couldn’t be reached or didn’t answer within 30 seconds. Check the network and retry.
`architect_detached`	You pressed Ctrl+C (exit `130`).
`viewer_invalid_build`	The build breaks a hosting rule: no top-level `index.html`, a symlink, an unsupported extension or path, or a size limit. Fix the build; a `--dry-run` shows the same errors.
`viewer_read_failed`	A file in the build couldn’t be read. The message names the file and the cause, such as permission denied.
`viewer_build_changed`	A file changed while the CLI was deploying it. Let the build finish, then run the command again.
`viewer_upload_timeout`	A file didn’t finish uploading before its deadline or the 15-minute upload window. Check the connection, then run the command again.
`viewer_upload_expired`, `viewer_upload_failed`	Storage refused an upload. Run the command again to start a fresh deployment.
`viewer_unauthorized`, `viewer_forbidden`	The key is invalid, revoked or an unclaimed agent key, or it can’t manage the viewer’s workspace. Check it with `pascal agent status`.
`viewer_not_found`	No hosted viewer with that ID is visible to this key. Check the ID under Settings → Viewers.
`viewer_conflict`	The viewer isn’t hosted on Pascal or is disabled or suspended, or the deployment didn’t match its uploads. The message says which; for a deployment problem, run the command again.
`viewer_rate_limited`	Too many deployments for this viewer in the last hour. Wait, then retry; the message gives the wait when Pascal sends one (exit `75`).
`viewer_unavailable`, `viewer_timeout`, `viewer_unreachable`	Viewer hosting is briefly down, didn’t answer in time, or couldn’t be reached. Check the network and retry (exit `75`).

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 Pascal API key for `pascal agent claim`, `pascal agent status`, `pascal architect` and `pascal viewer deploy`. 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
Ask the Architect over MCP: the same runs from an MCP client

Integrate

Extend Pascal

Install

Commands

Run the editor

Open projects

Update and diagnose

Connect MCP clients

Claim a hosted agent

Run the hosted Architect

Start a run

Run in the background

Check or cancel a run

Deploy a hosted viewer

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

Run the hosted Architect

Start a run

Run in the background

Check or cancel a run

Deploy a hosted viewer

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