DocsHaarness CLI

On this page

Fix common problems

Start with these two commands. Most problems show up in one of them.

haarness doctor          # version, bundled tools and where your data is
haarness logs --tail 50  # the end of the newest log file

haarness logs without --tail lists the log files and their folder. haarness --update installs the latest release (the terminal UI's home screen says when one is out); the haarness that comes with Haarness Desktop updates with Desktop instead.

Get more detail in the logs

haarness --log-level debug run "…"

Logs are always written to the log folder. --print-logs also prints them to the terminal. In the terminal UI that garbles the screen, so send them to a file:

haarness --log-level debug --print-logs 2>/tmp/haarness.log

To make the Haarness servers and apps that are already running log more, without restarting them:

haarness logs level debug           # for 30 minutes; --for 2h, or --until-stopped
haarness logs level stop            # back to normal

In Desktop, this is Detailed logging in Settings → General; in the terminal UI, /logs detail.

Send your logs with a bug report

haarness logs export

This packs the log files into haarness-logs-<time>.zip in the current folder, with tokens, passwords, keys and other known secret shapes replaced by [redacted]. Text you typed or a tool printed can still contain a secret, and paths and host names stay, so look through it before you send it. In Desktop, use Settings → General → Diagnostics → Export logs… or Help → Export logs…; in the terminal UI, /logs export.

The model I picked is rejected

haarness models             # the models you can use right now
haarness models openai      # one provider
haarness providers          # which providers are connected

Haarness asks each connected provider which models your credentials can use. If the provider is missing from haarness providers or not connected, sign in with haarness auth login <provider>; see Connect a provider. With a ChatGPT sign-in, a model your plan does not include is refused before the request, and the message lists the ones you can use.

`haarness run` uses the wrong model

Without -m, haarness run starts a new chat on your default model: the model in your configuration, or else one from a provider you connected. --continue and --thread keep the chat's own model. Pass -m provider/model to choose; haarness models lists the names.

A request to the provider failed

The error in the chat names the provider and gives its own message, not just a status code. It usually says what is wrong: an expired key, a usage limit, or a model you cannot use. A provider that cannot be reached is named with its address. Check the connection with haarness providers, and connect it again if the key was refused.

The agent cannot use a tool

In the terminal UI, /tools lists every tool and whether it is on. A tool can be turned off in tool_availability in your configuration, or removed for one agent with --tool name=false. A permission rule set to deny also blocks it; see Permissions.

A turn seems stuck

It may be waiting for your approval. Look for a permission prompt in the chat.
In Auto, it may show Reviewing… while a reviewer model checks a request. If the reviewer has not decided within 60 seconds, the request comes to you instead.
haarness run stopped with "nobody can approve that in this run". In a script or CI there is nobody to answer, so the request was refused. Allow what it needs in your permission rules, or pass --yolo. See Run a prompt from a script or CI.
To stop it, type /cancel, or press Esc twice. Ctrl+C clears your draft first, then stops the turn.
For helpers the agent started, /tasks lists them and opens their chats.

A tool call says "Stopped by Auto's reviewer"

In a chat in Auto, a reviewer model refused that request and told the agent why. Nothing ran. If you want it done, switch the chat to Review (Ctrl+Y in the terminal UI) and ask the agent to try again; this time the request comes to you. To stop the reviewer refusing that kind of request, say what is fine in your settings.

I closed the terminal. Is my turn still running?

Yes. Closing the terminal UI does not stop a turn; it keeps running on the Haarness server for that folder. Open the folder again with haarness --continue to see it. If you quit with Ctrl+D or /exit, the terminal UI printed the exact command to reopen that chat.

If the server stops while the terminal UI that started it is still open, the terminal UI starts it again by itself, and the status line says server stopped · restarting it.

To stop everything in that folder, run:

haarness serve --stop

This also ends any turn or workflow that is still running.

After a crash

Your chats are kept. Haarness does not re-run commands or file edits that were in progress; they are marked as interrupted. A workflow that was running is marked interrupted, and haarness workflow resume <run-id> starts it again from the beginning. A goal that was active comes back paused.

A language server or formatter is missing

The chat carries on without it. /status in the terminal UI shows each language server and formatter, and which ones are missing. Install the program, or turn it off in your configuration.

A project's settings cause the problem

Start without them:

haarness --disable-project-config

This ignores the project's settings, instructions, commands, agents, skills, MCP servers, workflows, plugins and extensions, and keeps yours.

Chrome does not connect

haarness browser status   # is Chrome set up, and which projects does it reach?
haarness browser setup    # set it up again

The Haarness button in Chrome says Not set up. Run haarness browser setup again, then check that Haarness is on at chrome://extensions and Developer mode is still on.
Chrome is connected, but the agent says it is not. The project's Haarness server may be older than the extension. When its work has finished, run haarness serve --stop in that project and open it again.
A work or school Chrome may block it by policy: see chrome://policy.
Chrome from Flatpak or Snap cannot start Haarness; haarness browser status says so.
A project on another computer cannot use your Chrome yet.

More causes and fixes are in Use your Chrome.

Where Haarness keeps its files

What	Default folder	Change it with
Settings (`haarness.json`, the terminal UI's `config.toml`), agents, commands, skills, workflows	`~/.config/haarness/`	`XDG_CONFIG_HOME`
Chats, credentials, logs	`~/.local/share/haarness/`	`XDG_DATA_HOME`
Caches and running servers	`~/.cache/haarness/`	`XDG_CACHE_HOME`
Haarness for Chrome: its helper and the extension folder you load	`~/.local/share/haarness/browser/chrome/`	`XDG_DATA_HOME`

These defaults apply on macOS and Windows too, with a few exceptions. On macOS, these still live in ~/Library/Application Support/dev.haarness.haarness/:

schedules and their logs
saved output of long commands
Canvas preview versions from Desktop

On Windows, the same things live in %APPDATA%\haarness\haarness\ and %LOCALAPPDATA%\haarness\haarness\.

Set HAARNESS_HOME to an absolute folder to move all of it, exceptions included, under one place: config/, data/, cache/ and state/ inside it. Your Haarness Cloud sign-in is kept in ~/.config/haarness-cloud/, or in config/account/ inside HAARNESS_HOME.

On macOS, terminal UI settings that an older version kept in ~/Library/Application Support/dev.haarness.haarness/config.toml still apply until ~/.config/haarness/config.toml sets them.