Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Meza-dev/Ghostly/llms.txt

Use this file to discover all available pages before exploring further.

Ghostly ships as a single npm package that brings everything it needs with it: a bundled API server, a React dashboard, a Playwright runner, and an MCP server for IDE integration. The steps below take you from zero to a running test on your local machine. All commands use the ghostly CLI (the legacy alias ghost also works for every command).
1

Install the Ghostly CLI

Install @ghostly-io/cli globally from npm. This is the only package you need — it bundles the API server, dashboard, runner, and MCP server.
npm install -g @ghostly-io/cli
Verify the installation:
ghostly --version
You should see 0.1.0 (or the latest published version). The command is ghostly; the alias ghost is kept for backwards compatibility.
2

Generate credentials

Run keygen to create a UUID API key and save it to ~/.ghostly/auth.json. This key is used to authenticate requests between the CLI, the local API server, and the MCP server.
ghostly keygen
Expected output:
Nueva API Key generada y guardada en ~/.ghostly/auth.json
Formato: uuid
apiKey: <your-uuid-here>
Pass --token to generate a random hexadecimal token instead of a UUID: ghostly keygen --token. Both formats are equally secure for local use.
The generated ~/.ghostly/auth.json stores your apiKey and the local API URL (http://localhost:4000 by default). Do not commit this file to version control.
3

Install IDE integration and Chromium

ghostly install does several things in one go: it saves credentials to ~/.ghostly/auth.json, injects the Ghostly MCP server into ~/.cursor/mcp.json, installs Chromium via Playwright (if not already present), and copies Cursor rules and skills to ~/.cursor/.
ghostly install
The installer is interactive — it will prompt before overwriting an existing MCP configuration, and before downloading Chromium if it is not yet installed. If you skip the Chromium download, you can install it manually at any time:
npx playwright install chromium
After install completes, restart Cursor to pick up the new MCP server entry in ~/.cursor/mcp.json.
4

Configure your LLM provider

Ghostly’s assisted mode (natural-language goals → Playwright steps) requires access to an LLM. Run ghostly config to choose your provider interactively.
ghostly config
The prompt lets you choose between:
ProviderWhen to use
cursor-cliYou already have Cursor installed and want to reuse its local auth — no separate API key needed.
HTTP (OpenAI-compatible)Any cloud or self-hosted endpoint: OpenAI, Azure OpenAI, Ollama, LM Studio, etc. You supply the base URL, model name, and API key.
Your choice is saved back to ~/.ghostly/auth.json under the llm key. You can also set ASSIST_LLM_API_KEY as an environment variable to skip this step in CI environments.
To reset the LLM configuration, run ghostly config --clear and then ghostly config again.
5

Start the Ghostly engine

ghostly up migrates the local SQLite database (via Prisma db push), generates the Prisma client, seeds the initial admin user on a fresh install, and then starts the bundled API server plus React dashboard.
ghostly up
Once running, you should see:
✅  Ghostly en ejecución

  Servicios:
  • Dashboard + API:   http://localhost:4000
  • Healthcheck:       http://localhost:4000/health

  Acceso inicial (seed):
  • Email:             admin@ghostly.local
  • Password:          admin123
Open http://localhost:4000 in your browser to access the dashboard.
The default admin credentials (admin@ghostly.local / admin123) are created automatically on the first run. Change the password immediately before exposing the dashboard on a shared network. You can update credentials from the dashboard’s settings panel or via the /v1/auth API.
To start on a different port, use the -p flag: ghostly up -p 3000. The API and dashboard will both be available at http://localhost:3000.
6

Create a project and run your first test

With the engine running, open the dashboard at http://localhost:4000 and sign in with the admin credentials.
  1. Create a project — click New Project, give it a name and colour, and save. Projects group your runs together for easier tracking.
  2. Submit a goal — from the project view, click New Run, enter your target URL (e.g. https://example.com) and a plain-English goal (e.g. “Navigate to the homepage, click the Learn More button, and confirm the About section is visible”).
  3. Watch it run — Ghostly streams live step events via SSE to the dashboard. You can see each Playwright action as it executes, inspect screenshots, and review the final verdict.
You can also trigger a run directly from Cursor using the ghostly_run_flow MCP tool once ghostly up is running.

​
Next steps

CLI Reference

Explore every flag and option for keygen, install, config, up, and update.

Assisted Mode

Learn how the strategist–observer–healer pipeline converts natural-language goals into Playwright steps.

MCP Server

Trigger Ghostly runs and inspect project maps directly from your Cursor editor via MCP.

Build docs developers (and LLMs) love

Get started for freeTalk to us