Skip to main content
Start the daemon that powers the Percio CLI. You rarely need to run this explicitly — other commands auto-start the daemon — but you will use it for MCP mode, pinned ports, and troubleshooting.

​
Synopsis

​
Options

​
Examples

Foreground (default). Best for integrated terminals where you want the shell to stay usable while the daemon runs:
Detached. Runs in the background, returns immediately, and prints the port it bound to:
Pinned port. Useful when you’re integrating with something that needs to know the port ahead of time:
MCP mode. Starts the daemon with the MCP server attached to stdio. This is what percio-mcp does under the hood, and what your Cursor config invokes:

​
What it does

  • Binds an HTTP server to 127.0.0.1 (localhost only).
  • Writes a lockfile so future CLI commands know how to reach it.
  • Creates .perciorc.json in the current directory if one doesn’t exist.

​
Auto-start

Every other CLI command (percio test, percio personas list, etc.) will auto-start the daemon if one isn’t running. You don’t need to call percio start unless you want one of the scenarios above.

​
Checking it’s running

After a detached start, the daemon port is printed to your terminal. You can also check via any CLI command that talks to the daemon — they’ll fail fast if the daemon is unreachable.

​
What’s next