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

# Run Pascal locally

> Install and manage a persistent local Pascal Editor with the command-line interface.

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](https://nodejs.org/en/download) 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:

```bash theme={null}
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:

```bash theme={null}
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:

1. Prepares the local data directory and copies its bundled editor into
   `~/.pascal/runtime/<version>`.
2. Asks the operating system for an available loopback port.
3. Starts the editor and an authenticated MCP service as detached processes on
   separate operating-system-assigned loopback ports, then waits for both health checks.
4. Opens `http://pascal.localhost:<port>` in your browser and, for an interactive
   `npx` run, installs the same CLI version globally.
5. 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:

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

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

```bash theme={null}
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:

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

Update the global command separately from the managed editor runtime:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/docs/developers/plugins), use the
[Nature plugin](https://github.com/pascalorg/plugin-trees) 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.

```bash theme={null}
# 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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/developers/mcp). Claude plugin users must disable the
plugin-provided local server in `/mcp` before adding the hosted connection.