Run Pascal locally

The Pascal CLI creates a persistent local installation of the open-source editor, runs the editor and its MCP server in the background, and opens the editor in your browser. It does not create a JavaScript project or require a checkout of the Pascal repository. Your runtime and project data live outside the package-manager cache. The background process survives closing the terminal, while the runtime and projects also survive a reboot. Run editor again after a reboot to restart the process.

Requirements

Node.js 22.13 or newer
npm, which is included with standard Node.js installations and is used by pascal update
A browser if you want the CLI to open the editor automatically

The initial CLI release supports macOS. Linux and Windows support is not verified yet.

Start the editor

Run the package directly:

npx @pascal-app/cli editor

After an interactive npx first run makes the editor healthy, Pascal installs that exact CLI version globally through npm. The shorter pascal command is then available immediately in the current terminal and future sessions. Pascal does not modify a shell profile or add an alias; npm places the executable in its configured global binary directory, which Node.js installations normally add to PATH. Non-interactive and --json runs do not install a global command. If npm cannot perform the global installation because of local permissions, the editor remains running and the CLI prints the equivalent npx commands plus the manual installation command. You can use an equivalent package runner to launch the CLI:

pnpm dlx @pascal-app/cli editor
bunx @pascal-app/cli editor

These forms still require npm to be available because the CLI’s update command uses npm to resolve another published release. Automatic installation of the shorter command currently applies to interactive npx first runs; use the global installation command below after pnpm dlx or bunx. On the first run, the CLI:

Prepares the local data directory and copies its bundled editor into ~/.pascal/runtime/<version>.
Asks the operating system for an available loopback port.
Starts the editor and an authenticated MCP service as detached processes on separate operating-system-assigned loopback ports, then waits for both health checks.
Opens http://pascal.localhost:<port> in your browser and, for an interactive npx run, installs the same CLI version globally.
Prints the direct pascal status, pascal logs --follow, and pascal stop commands.

The reserved .localhost hostname resolves to the loopback service; it is not exposed to your network. The CLI shows each setup and startup stage in the terminal. It does not assume port 3000 or scan a fixed range, so it avoids competing with other development servers. A value passed with --port requests that specific port; when it is already occupied, Pascal reports the conflict and safely selects an available port instead. Running editor again reuses the healthy process instead of starting a second one; in that case --port does not move the existing process. Stop or restart the editor to select a new port. Use --no-open on a headless machine or when you do not want to launch a browser:

npx @pascal-app/cli editor --no-open

Use --foreground to keep the editor attached to the current terminal for debugging:

npx @pascal-app/cli editor --foreground --no-open

start and editor --no-open both install the bundled runtime if needed and ensure it is running without opening a browser. start is the shorter lifecycle command for that operation.

Install the command globally first

The interactive npx flow handles this automatically. You can instead install the shorter pascal command before starting the editor:

npm install --global @pascal-app/cli
pascal editor

Update the global command separately from the managed editor runtime:

npm install --global @pascal-app/cli@latest

Command reference

Command	What it does
`pascal editor [--foreground] [--no-open] [--port <n>]`	Install the bundled runtime if needed, ensure it is running, and open it.
`pascal start [--foreground] [--port <n>]`	Install if needed and ensure the editor is running 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`	Stop and start the managed editor and MCP service.
`pascal status [--json]`	Summarize editor and MCP health; `--json` also includes PIDs, ports, URL, runtime, and process metadata.
`pascal open [project]`	Start Pascal if needed, then open the editor or a project selected by ID, unique ID prefix, or unique name.
`pascal resume [project]`	Open the most recently edited project, or resume the selected project.
`pascal projects [--json]`	List local projects, starting Pascal if needed.
`pascal logs [--follow] [--lines <n>]`	Read or follow the editor log.
`pascal update [--version <version>]`	Install and activate the runtime bundled with the latest or specified CLI release.
`pascal doctor [--json]`	Check Node.js, storage, runtime, process health, and plugin state.
`pascal info [--json]`	Print runtime, platform, storage, and plugin context.
`pascal project list [--json]`	Explicit form of `pascal projects`.
`pascal project open <id-or-name>`	Explicit form of `pascal open <project>`.
`pascal project resume [id-or-name]`	Explicit form of `pascal resume [project]`.
`pascal agent claim [--no-open] [--json]`	Request a hosted autonomous-agent claim code and optionally open the prefilled human claim page.
`pascal agent status [--json]`	Verify a hosted agent key and report its agent ID, mode, claim state, and organization scope.
`pascal mcp connect`	Stable stdio connector used by local MCP clients; it discovers the current dynamic MCP port.
`pascal mcp status [--json]`	Show managed MCP process health.
`pascal mcp config [--json]`	Print a generic MCP client configuration.
`pascal mcp setup <codex\|claude>`	Add the managed connector to Codex or Claude Code. Existing entries are never overwritten.
`pascal plugin list [--json]`	Inspect the reserved managed-plugin lock; it is normally empty in this release.

For a non-interactive installation where the global command is unavailable, prefix a command with your package runner—for example, npx @pascal-app/cli status. pascal agent claim and pascal agent status contact hosted Pascal. They read the agent key from PASCAL_API_KEY and do not store or print it. Claim requests a short-lived code; status verifies the key and reports its bounded claim state. Neither command uploads or links local projects. Direct integrations can call POST /api/auth/agent/claim/start and GET /api/auth/agent/status with the same Bearer key instead.

Update the editor

Install and activate the editor runtime that the latest published CLI package targets:

npx @pascal-app/cli update

Or select an exact published CLI package and the runtime it targets. Replace 1.0.0 with the version you need:

npx @pascal-app/cli update --version 1.0.0

An update installs the candidate under ~/.pascal/runtime, starts it through the normal health gate, and only leaves it active when that check passes. If activation fails, the CLI restores the previous runtime and restarts the previous editor when it was running. It does not replace ~/.pascal/data/pascal.db or update a globally installed pascal command.

Files and persistence

Path	Contents
`~/.pascal/runtime/<version>/`	Installed, versioned editor runtimes
`~/.pascal/data/pascal.db`	Local projects and scenes
`~/.pascal/logs/editor.log`	Detached editor output
`~/.pascal/run/editor.json`	Managed process identity, URL, and runtime version
`~/.pascal/run/mcp-token`	Private bearer token used only by the local MCP connector
`~/.pascal/run/current-runtime.json`	Active runtime pointer
`~/.pascal/plugins/`	Reserved storage for verified plugin artifacts
`~/.pascal/pascal.plugins.lock`	Managed plugin versions and integrity metadata

Runtime, data, logs, and process state have separate lifecycles. The CLI has no command that deletes project data. Runtime versions remain installed to make rollback possible, and pascal doctor warns after more than three versions accumulate. There is no automated prune command in the initial release. When disk space is constrained, stop Pascal and remove only version directories that are not named by current-runtime.json. Never remove the data directory when pruning runtimes. Before each detached start, an existing editor.log larger than 10 MiB rotates to editor.log.1. One previous log is retained. The paths above use Unix notation. On Windows, the same .pascal directory is under your user profile. Run npx @pascal-app/cli info --json to see the resolved paths on your machine.

Troubleshooting

Start with diagnostics, then inspect the process and log:

npx @pascal-app/cli doctor
npx @pascal-app/cli status
npx @pascal-app/cli logs --lines 200
npx @pascal-app/cli editor --foreground --no-open

Pascal selects an available port automatically. If you request a port with --port and another application owns it, the CLI reports the fallback port in the terminal.
If an interactive npx run cannot install the global command, it reports the npm failure without stopping the editor. Continue with npx @pascal-app/cli status or resolve your npm global-install permissions and run npm install --global @pascal-app/cli.
A reboot stops the editor process. Run npx @pascal-app/cli editor again; the initial CLI does not install a system startup service.
If the installed copy of the runtime bundled with the current CLI is incomplete or damaged, pascal editor replaces that runtime copy and starts it again. Project data remains separate under ~/.pascal/data.
The CLI refuses to stop a recorded PID unless its health endpoint returns the same Pascal instance identifier. This prevents a stale state file from stopping an unrelated process. If the recorded editor is alive but its health route is unavailable, inspect pascal status --json and use pascal stop --force; the CLI still verifies that the operating-system command points to the recorded runtime before signaling it.
Pascal binds only to loopback and does not expose an unauthenticated editor to your network. Public/LAN binding is not supported in the initial release.

Plugin development

The CLI currently manages the editor runtime; it does not install plugin code from a GitHub repository or npm. plugin add, plugin remove, plugin validate, and plugin pack are not available yet. The reserved plugin directory and lock file do not make the managed runtime extensible in this release. To develop a plugin today, follow Create a plugin, use the Nature plugin as the standalone example, and integrate the package through the reviewed discovery configuration in a host source checkout. The CLI-managed runtime cannot be modified to load that source package.

Connect a local AI agent

pascal editor starts MCP automatically. The MCP port remains dynamic to avoid collisions, while pascal mcp connect gives clients a stable stdio command that reads the private runtime state and connects to the current port. You do not copy the local token or manage another server.

# Configure Codex once
pascal mcp setup codex

Pascal agent skills 0.1.7 already supplies the same local connector to Claude Code. If that plugin is installed, do not also run pascal mcp setup claude. Remove a previous user-scoped manual entry before reloading or restarting Claude Code:

claude mcp remove --scope user pascal

Use /mcp to remove or disable any project- or local-scoped duplicate so only plugin:pascal-agent-skills:pascal remains active. If you use Claude Code without the plugin, pascal mcp setup claude remains the manual setup path. For Cursor, Claude Desktop, and other mcp.json clients:

{
  "mcpServers": {
    "pascal": {
      "command": "pascal",
      "args": ["mcp", "connect"]
    }
  }
}

The connector starts Pascal automatically if it is stopped. Ask the agent to read pascal://agent-guide, call list_scenes, then load_scene before editing an existing project. MCP saves use the same ~/.pascal/data/pascal.db database and appear in the browser through the local scene event stream. setup requires the stable pascal command and refuses to overwrite an existing Pascal MCP entry. Run pascal mcp config to print the generic JSON or configure a different client manually. To edit projects in your hosted Pascal account instead, use the authenticated hosted setup in Connect an AI agent. Claude plugin users must disable the plugin-provided local server in /mcp before adding the hosted connection.

Integrate

Extend Pascal

Run Pascal locally

Requirements

Start the editor

Install the command globally first

Command reference

Update the editor

Files and persistence

Troubleshooting

Plugin development

Connect a local AI agent

​Requirements

​Start the editor

​Install the command globally first

​Command reference

​Update the editor

​Files and persistence

​Troubleshooting

​Plugin development

​Connect a local AI agent

Requirements

Start the editor

Install the command globally first

Command reference

Update the editor

Files and persistence

Troubleshooting

Plugin development

Connect a local AI agent