Reference

Command line

Run pointfix commands inside your app’s repository. Configuration is discovered upward from the current folder.

pointfix <command> [--flag=value …]
Commands
CommandWhat it does
initSet up Pointfix in this project (writes pointfix.config.json).
doctorCheck Node, configuration, agents, subscriptions and platform tools.
startStart the bridge for this project, with a live terminal dashboard.
stopStop this project’s bridge, or clear a lock left by one that crashed.
statusShow whether this project’s bridge is running, and its queue.
openOpen the Pointfix Mac app, installing it first if needed.
configShow the resolved configuration and settings.
help, --help, -hShow help. Running pointfix alone does the same.
--version, -vPrint the version.
Flag syntax

Write values with an equals sign: --port=4848. A space-separated value (--port 4848) is not read as the flag’s value.

An unknown command prints the help and exits with status 2. A failing command prints pointfix <command>: <message> and exits with status 1. POINTFIX_CONFIG, POINTFIX_PROJECT and POINTFIX_PORT override the configuration for every command; see Environment variables.

init

pointfix init [--agent=ID] [--port=4747] [--origin=http://localhost:5173] [--yes] [--project=PATH]
init flags
FlagEffect
--agent=IDThe default agent: claude, codex, cursor, gemini, copilot, opencode, droid, qwen, amp, goose, aider or custom. Otherwise the existing defaultAgent, else the first supported agent on your PATH, else codex.
--port=NThe bridge port, 1024–65535. Otherwise the existing port, else 4747.
--origin=URLAdds a web dev origin to allowedOrigins.
--yesDon’t ask questions. Without it, an interactive terminal is asked for the agent and port.
--project=PATHSet up this folder instead of the detected project root. Not shown in help.

init keeps existing settings in pointfix.config.json, sets project to "." if missing and autoDispatch to true if missing, merges detected dev origins, adds .pointfix/ to .gitignore, and prints the SDK snippet for each detected platform (web if none). See Set up a repository.

doctor

pointfix doctor

Checks, in order:

  • Node.js is version 20 or newer.
  • The configuration loads, and pointfix.config.json exists (a warning suggests init if not).
  • The project is a Git repository (a warning if not).
  • A Pointfix bridge for this project is running on the port, or the port is free. A bridge for another project, or another program on the port, is a problem.
  • The selected agent (from Preferences, else defaultAgent) is installed.
  • Claude Code and Codex are installed and signed in with a subscription. This is a problem for the selected agent unless useApiKeys is on, otherwise a warning.
  • xcodebuild for iOS projects and adb for Android projects (warnings).

It ends with Everything looks ready. or the number of problems, and exits with status 1 if there are any.

start

pointfix start [--port=N] [--plain]

Starts the bridge in the foreground. In a terminal it shows a live dashboard: report counts and token usage, the pipeline from captured to shipped, the queue, the agent’s current run with its tool calls, activity over the last minutes and an event log. Keys: q stops the bridge, o opens the Pointfix Mac app, c clears finished reports. --plain, or output that isn’t a terminal, prints the URL and project instead. With "remote": true, it also shows the URLs other Macs can use. q, Ctrl + C or closing the terminal stops it; an active run is stopped and marked interrupted. --port overrides the configured port for this run.

A lock left by a bridge that exited without stopping cleanly is reclaimed automatically.

stop

pointfix stop [--force]

Stops the bridge running for this project, from any terminal, and waits up to 15 seconds for it to release its lock. If the bridge has already exited, it removes the stale lock. --force kills a bridge that hasn’t stopped in that time.

status

$ pointfix status
Pointfix 0.2.0 running at http://127.0.0.1:4747
Project  /Users/you/your-app
Agent    claude (sonnet)
Auto     mode on · relaunch off · commit off
Reports  12 total · 1 working · 2 to review · 0 need attention

“Working” counts queued, fixing, checking and rebuilding reports; “need attention” counts failed, interrupted and stopped ones. Exits with status 1 if this project’s bridge isn’t running, or if the port serves another project.

open

pointfix open

Opens the Pointfix Mac app. If it isn’t installed, installs it with Homebrew (brew install --cask pointfix-dev/tap/pointfix) and then opens it; without Homebrew it opens pointfix.dev/download and exits with status 1.

config

pointfix config

Prints the configuration file in use (or none; using defaults), the resolved configuration as JSON, and the saved Preferences from .pointfix/settings.json.