CLI

Terminal agent · updated 5 Oct 2026

HowToFix ships a coding agent that runs in your terminal and bills to the same account as the API. One install, one sign-in, every model your account can reach.

1. Install

Node 22.19 or newer is required. Check with node --version, then install from the npm registry:

npm install -g howtofixcli
howtofix --version

The package is the artifact — there is no separate download. Pin an exact release with npm install -g howtofixcli@0.4.45, and the built-in updater checks the same registry for a newer one.

If howtofix is not found afterwards, your npm prefix is not on PATH. Fix it with export PATH="$(npm config get prefix)/bin:$PATH", or reinstall with npm install -g --prefix /usr/local howtofixcli.

2. Connect your account

One account covers the API and the CLI. Every model on the gateway is billed to it.

1. Create the account at Sign up — Google sign-in works, and only @gmail.com addresses are accepted.
2. Open Console → Tokens and create a token. It starts with sk-. Treat it like a password; it is the only thing you have to copy.
3. Run howtofix and type /connect. It opens the token page and asks you to paste the token.

howtofix
/connect

You can also skip the prompt by passing the token on the same line — useful in a script:

/connect sk-you...here

The token is verified against the gateway before it is stored, and your model list is pulled in at the same time, so /model shows everything the account can reach. Nothing is written until the gateway accepts the token.

Sign in without copying a token

/connect can start a browser sign-in instead of asking for a paste: the CLI shows a link, you open it, approve, and the key lands in the CLI on its own. The approval page names the machine that asked, so you can confirm it is yours before you click. The approval code travels in the URL and is treated as semi-public — the key is only handed to a request that also carries a secret value that never leaves the CLI process, so seeing the link is not enough to collect a key.

/login is different: it stores an API key for another provider (for example an Anthropic key) so you can reach models outside the gateway. To attach your howtofix.id account, use /connect.

Free tier, updating and removing

• Free tier — /connect verifies against the paid account first and the free one second, so the same command works for both; the models simply land under howtofix-free. /providers shows which one your token is attached to.
• New token — run /connect again with the new value. It replaces the stored token and re-syncs models; models you configured by hand are never overwritten.
• Remove — /logout clears the stored key. The account itself is untouched.

3. First run

howtofix                                  # open the workbench
howtofix "fix the failing test in src/auth"
howtofix -p "explain this repo" | less    # one prompt, print the answer
howtofix -c                               # continue the last session here

The workbench is a scrolling feed of turns, tool calls and streamed answers, a boxed input dock, and one HUD line showing model, folder, git branch, context meter, thinking level, approval mode and activity. Type /model to pick a model, then just describe what you want.

• @src/main.ts in a prompt inlines a file; paths that do not exist are left for the agent to read.
• A line starting with ! runs in the project shell and stays in the session history.
• Esc stops the current run; Ctrl+C does the same, and quits when idle.

4. Commands

5. Approval and safety

Three approval modes decide what the agent may do without asking:

Two rules hold in every mode, including full-auto:

• Read-only commands never ask. ls, git log, grep and pipes like ls | head run silently — so reading your own repo never stops the run.
• Critical commands are denied. Anything that can destroy the machine (a host shutdown, a reboot, a wipe) is refused in every mode. A word is not an action: grep shutdown src/ is allowed, shutdown is not.

Pick a mode with /approval or --approval <mode>. Permission checks can be lifted entirely for an unattended run — /settings permissions (or /settings on|off) in the workbench, or --dangerously-skip-permissions for a single --print run. Turning them off lifts the last two refusals and says so: a banner on start and a warning row in the HUD for as long as it is off.

6. Scripting and CI

For machine-readable output, pair --print with --output-format:

howtofix --print --output-format json -p "summarise src/" \
  | jq -c 'select(.type == "result") | {subtype, total_cost_usd, result}'

With json/stream-json the first line is a system/init header (model, session id, budget, bypass) and the last is a result record carrying subtype (success, error_max_budget_usd, error_aborted, error_during_execution), is_error, total_cost_usd and token usage. Nothing has to be scraped from the terminal.

howtofix --print --max-budget-usd 0.50 -p "add tests for src/auth"

--max-budget-usd stops a run once it has spent that many dollars and reports error_max_budget_usd. It needs a model with declared prices — if the model has none, the CLI refuses to start rather than run unmetered.

7. Config and sessions

Everything lives under ~/.howtofix/agent:

Set HOWTOFIX_CODING_AGENT_DIR to use a different root. Sessions are stored per project, so -c resumes the latest one in the current folder and /resume picks any of them. Run /init to write an AGENTS.md that the agent loads into its system prompt on later runs.

8. Skills

Drop a SKILL.md in ~/.howtofix/agent/skills/<name>/ (user-wide) or .howtofix/skills/<name>/ (this project). /skills lists them, /skill:name loads one into the next turn, and the model sees the list so it can read a matching skill on its own.

9. Update

npm install -g howtofixcli@latest   # from the registry
howtofix --update                   # or let the CLI install it
howtofix --check-update             # just ask whether one exists

An npm install checks for a newer release at startup and can install it itself; /update does the same on demand from inside the workbench.

10. Troubleshooting