Troubleshooting with markata triage

When your Markata site behaves unexpectedly, start with:

markata triage

Markata collects lightweight local diagnostics, then displays a fuzzy picker with the coding agents it finds on your PATH. It also offers Copy to clipboard and Print to stdout. Pick a coding agent and the agent opens with a troubleshooting prompt: it should ask you what happened first, instead of making guesses or immediately modifying your site.

The command works with the new markata binary and the backwards-compatible markata-go binary.

Where the prompt goes

Harness detection only checks that an executable is on PATH. It does not guarantee the agent is authenticated or configured with a model. Unsupported or missing agent names produce an error; clipboard and stdout still work.

For Linux clipboard handoffs, install wl-copy, xclip, or xsel. macOS uses pbcopy; Windows uses clip.exe. A missing helper is reported as an error; use stdout instead.

Piping to an agent

--to stdout is clean Markdown with no banner, terminal formatting, or interactive picker. It can be redirected to a file or piped directly into another CLI:

# Interactive picker disabled automatically in a pipe
markata triage --to stdout | codex exec -

# Use OpenCode's noninteractive prompt runner
markata triage --to stdout | opencode run

# Use Claude Code's print mode
markata triage --to stdout | claude -p

# Save and inspect the context before sharing it
markata triage --to stdout > triage-prompt.md

Piped agent commands may be noninteractive. If you want the agent to ask questions back-and-forth in a terminal, use --to opencode, --to claude, etc., or select an agent from the fuzzy picker.

With --no-input, or if stdin or stdout is not a terminal, the default --to auto prints to stdout; it never unexpectedly launches an agent. Explicit interactive agent launch requires a terminal. Press Escape to cancel the fuzzy picker without launching anything. Closing a pipe early (for example, markata triage | head) exits quietly. The primary prompt remains plain and pipeable with --no-color, NO_COLOR, and --quiet.

Triage remains available even when a requested --site-dir or MARKATA_GO_SITE_DIR directory is missing or inaccessible; it records that problem in its diagnostics instead of failing before collecting context. Config file contents are never parsed as part of triage.

What is collected

The prompt describes: - The running triage CLI's embedded version, commit, and build date - Operating system, architecture, Go runtime, and (on Linux) OS distribution - Location of the Markata executable and an inferred, not guaranteed, installation method - Working/site directory and names of local Markata config files (or explicit config path) - Presence of a small allowlist of environment variables, not their values - Links to Markata's source, documentation, and issue tracker

It does not read your configuration contents, logs, passwords, authentication tokens, arbitrary environment values, or other user files. Home-directory prefixes in paths are abbreviated when possible. Because paths may still be personal, inspect the prompt before sharing it publicly or sending it to a new provider.

A key distinction: the Markata version used to generate the prompt may be different from the version that failed in production, Docker, CI, or a remote builder. The agent is instructed to ask which version and execution environment actually experienced the problem.

What the agent should do

The prompt asks the agent to first understand your symptoms, intended behavior, reproduction steps, and exact errors. It should check whether the issue is with site content, configuration, templates, a plugin, installation, or Markata itself; investigate read-only first; and ask permission before changing files, running mutating commands, or publishing an upstream issue.

If you already have a clear problem statement, add --issue and the agent should not make you repeat it.

For common manual troubleshooting, see the Troubleshooting guide and the CLI reference. The source repository and issue tracker are available when a fix belongs upstream.