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

percio start [options]

​
Options

FlagDescription
-d, --detachRun the daemon in the background and return immediately.
--mcpStart with the MCP server enabled on stdio. Used by percio-mcp.
--port <number>Pin the daemon to a specific port instead of picking one at random.

​
Examples

Foreground (default). Best for integrated terminals where you want the shell to stay usable while the daemon runs: 
percio start
Detached. Runs in the background, returns immediately, and prints the port it bound to: 
percio start -d
# Daemon started in background at http://127.0.0.1:52431. Use percio stop to stop.
Pinned port. Useful when you’re integrating with something that needs to know the port ahead of time: 
percio start --port 5174
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: 
percio start --mcp

​
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