CLI Troubleshooting

CLI

Common CLI-level issues. For plugin-specific problems (commands not appearing, host-specific hooks), see plugin troubleshooting.

For a quick all-in-one check, run:

archcore doctor

This validates your project context — settings.json, document structure, MCP configuration, and server reachability — in one pass. The output tells you exactly what’s wrong and how to fix it.

Agent cannot see documents

Your agent says it can’t find any documents, or it doesn’t seem to know about Archcore at all. Work through the checks below in order — they’re arranged from most common to least common.

MCP not configured

The agent needs an MCP server configuration to connect to Archcore. Without it, the agent has no way to discover or read your project context.

Check: Look for the MCP config file for your agent:

Agent	Config file
Claude Code	.mcp.json
Cursor	.cursor/mcp.json
GitHub Copilot	.vscode/mcp.json
Gemini CLI	.gemini/settings.json
OpenCode	opencode.json
Codex CLI	.codex/config.toml
Roo Code	.roo/mcp.json
Cline	VS Code globalStorage (manual setup)

Fix: Run the setup command:

archcore mcp install

Or re-run full initialization, which also installs hooks:

archcore init

Both commands auto-detect your agents and write the correct config files. See Agent integrations for the full agent registry.

Config points to wrong command

The MCP config JSON tells the agent what command to run. If the command or args fields are wrong, the server won’t start and the agent won’t see any documents.

Check: Open your agent’s MCP config file and verify it matches this structure:

{
  "mcpServers": {
    "archcore": {
      "command": "archcore",
      "args": ["mcp"]
    }
  }
}

For GitHub Copilot, the format is slightly different:

{
  "servers": {
    "archcore": {
      "type": "stdio",
      "command": "archcore",
      "args": ["mcp"]
    }
  }
}

Fix: Regenerate the config:

archcore mcp install

See Agent integrations for config file locations per agent.

Archcore not in PATH

The MCP server runs as a subprocess — your agent executes archcore mcp behind the scenes. If the archcore binary isn’t in your shell PATH, the agent can’t launch it and reports “command not found.”

Check:

which archcore

If this returns nothing, the binary isn’t in your PATH.

Fix: Add the directory containing archcore to your PATH. The exact location depends on how you installed it:

• macOS / Linux (install.sh): typically ~/.local/bin/archcore or /usr/local/bin/archcore. Add to your shell profile (~/.bashrc, ~/.zshrc, or equivalent).
• Windows (install.ps1): typically %LOCALAPPDATA%\Programs\archcore\archcore.exe. The installer adds this directory to your user PATH automatically — if it’s missing, open a new PowerShell window or re-run the installer.

Then verify:

archcore --version

If you haven’t installed Archcore yet, follow Install.

Wrong working directory

The MCP server looks for .archcore/ relative to the current project root. If you opened your editor in a parent directory, a subdirectory, or a different project entirely, the server won’t find your documents.

Check:

ls .archcore/

If this shows “No such file or directory,” you’re not in the right project root.

Fix: Open your editor or terminal in the directory that contains .archcore/. For multi-root workspaces, make sure the project with .archcore/ is the active workspace root.

If you haven’t initialized the project yet:

archcore init

Hooks not installed

Without session hooks, the agent doesn’t receive project context when a conversation starts. The agent can still use MCP tools if configured, but it won’t proactively check for documents.

Check: For Claude Code, look for the hook in .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "archcore hooks claude-code session-start"
          }
        ]
      }
    ]
  }
}

Fix:

archcore hooks install

This installs hooks for all detected agents. See Hooks for agent-specific details.

Agent doesn’t support MCP

Some agents or agent modes don’t support the Model Context Protocol. If your agent isn’t in the agent integrations list, it can’t connect to the Archcore MCP server.

Supported agents: Claude Code, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Codex CLI, Roo Code, Cline.

If your agent isn’t listed, you can still use Archcore documents manually — they’re standard Markdown files in .archcore/ that any tool can read.

Documents exist but agent says none found

The agent connects to MCP successfully but reports zero documents. This usually means your documents have validation errors and are being skipped.

Check:

archcore status

This reports any issues with file naming, frontmatter, or document structure.

Common causes:

• Filename doesn’t match slug.type.md pattern (spaces, underscores, or uppercase in the slug)
• Missing or invalid YAML frontmatter (title and status are required)
• Unknown document type in the filename

Fix: Correct the issues reported by archcore status. See Validation errors below for detailed guidance on each error type.

MCP server not starting

The MCP server runs as a subprocess that your coding agent launches automatically. When it fails to start, the agent either reports an MCP error or silently loses access to your repo context.

Permission denied

On macOS and Linux, the binary needs execute permissions. The install script sets this automatically, but manual downloads or file transfers can strip it.

Check:

ls -l $(which archcore)

Look for x in the permissions (e.g., -rwxr-xr-x).

Fix:

chmod +x $(which archcore)

Multiple archcore versions

If you have multiple installations (e.g., a global install and a project-local one), the agent might pick up the wrong version.

Check:

which archcore
archcore --version

On some systems, you can also check for duplicates:

which -a archcore

Fix: Remove the extra installation, or ensure your PATH resolves to the correct one first. After fixing, regenerate the config:

archcore mcp install

Validation errors

archcore status checks every document in .archcore/ for correct naming, structure, and frontmatter.

Invalid filename

What you see: The file doesn’t match the slug.type.md pattern.

Why it happens: Slugs must be lowercase alphanumeric with hyphens only. The filename must follow the exact format slug.type.md — no extra dots, no spaces, no underscores.

Examples of invalid names:

Filename	Problem
My Decision.adr.md	Spaces and uppercase
jwt_strategy.adr.md	Underscores
UsePostgres.adr.md	Uppercase letters
api.v2.migration.adr.md	Extra dots in the slug

Fix: Rename the file to use a valid slug:

mv ".archcore/My Decision.adr.md" ".archcore/my-decision.adr.md"
mv ".archcore/jwt_strategy.adr.md" ".archcore/jwt-strategy.adr.md"

Slugs must match ^[a-z0-9]+(-[a-z0-9]+)*$. See Document format for the full spec.

Unknown document type

What you see: The type portion of the filename isn’t recognized.

Why it happens: The type (the middle part of slug.type.md) must be one of the 18 valid types.

Valid types:

adr, rfc, rule, guide, spec, doc, prd, idea, plan, task-type, cpat,
mrd, brd, urd, brs, strs, syrs, srs

Common mistakes:

Filename	Problem	Fix
auth.decision.md	decision is not a type	Rename to auth.adr.md
setup.tutorial.md	tutorial is not a type	Rename to setup.guide.md
api-spec.reference.md	reference is not a type	Rename to api-spec.spec.md or api-spec.doc.md

Fix: Rename the file using one of the 18 valid types. See Document types for guidance on choosing.

Missing frontmatter

What you see: The document is missing YAML frontmatter, or the frontmatter is missing required fields.

Why it happens: Every Archcore document requires YAML frontmatter with both title and status fields.

Fix: Add the required frontmatter at the top of the file:

---
title: Use PostgreSQL as Primary Database
status: draft
---

Your document content here...

Both fields are required:

Field	Type	Required values
title	string	Any non-empty string
status	string	draft, accepted, or rejected

Invalid status

What you see: The status field contains an unrecognized value.

Why it happens: Status must be exactly one of three values. Not active, not approved, not archived.

Status	Meaning
draft	Work in progress (default for new documents)
accepted	Finalized or approved
rejected	Superseded, abandoned, or declined

Fix: Update the frontmatter to use a valid status.

Orphaned relations

What you see: A relation points to a document that no longer exists on disk.

Why it happens: You deleted or renamed a document, but the relation referencing it still exists in .sync-state.json.

Fix:

archcore doctor --fix

This automatically removes orphaned relations from the manifest before running checks.

Invalid tags

What you see: A tag doesn’t match the required format.

Why it happens: Tags must be lowercase and match ^[a-z][a-z0-9_:|-]*$.

Tag	Problem
Frontend	Uppercase letters
my tag	Spaces
123-start	Must start with a letter

Fix: Correct the tag value. Archcore shows a “did you mean?” hint when a tag is rejected.

Invalid YAML

What you see: The frontmatter can’t be parsed as valid YAML.

Why it happens: Syntax error between the --- delimiters. Common causes:

• Missing closing ---
• Tabs instead of spaces
• Unquoted special characters (colons, brackets) in values

Fix: Correct the YAML syntax. If unsure, start with a minimal frontmatter block:

---
title: Your Title Here
status: draft
---

Using --fix

archcore doctor --fix automates what it can:

• Removes orphaned relations from .sync-state.json before running checks
• Saves the cleaned manifest

It does not auto-fix invalid filenames, missing frontmatter, unknown document types, or YAML syntax — you have to correct those manually.

For a full project health check:

archcore doctor

See Commands for details.