Command line
Run pointfix commands inside your app’s repository. Configuration is discovered upward from the current folder.
pointfix <command> [--flag=value …]
| Command | What it does |
|---|---|
init | Set up Pointfix in this project (writes pointfix.config.json). |
doctor | Check Node, configuration, agents, subscriptions and platform tools. |
start | Start the bridge for this project, with a live terminal dashboard. |
stop | Stop this project’s bridge, or clear a lock left by one that crashed. |
status | Show whether this project’s bridge is running, and its queue. |
open | Open the Pointfix Mac app, installing it first if needed. |
config | Show the resolved configuration and settings. |
help, --help, -h | Show help. Running pointfix alone does the same. |
--version, -v | Print the version. |
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]
| Flag | Effect |
|---|---|
--agent=ID | The 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=N | The bridge port, 1024–65535. Otherwise the existing port, else 4747. |
--origin=URL | Adds a web dev origin to allowedOrigins. |
--yes | Don’t ask questions. Without it, an interactive terminal is asked for the agent and port. |
--project=PATH | Set 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.jsonexists (a warning suggestsinitif 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
useApiKeysis on, otherwise a warning. xcodebuildfor iOS projects andadbfor 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.
Pointfix