CLI Commands

CLI

archcore init

Initialize .archcore/ in the current directory.

archcore init

What it does:

Creates .archcore/ directory with settings.json
Auto-detects installed coding agents
Installs MCP server config for detected agents
Installs lifecycle hooks for supported agents
Offers to write the “use Archcore” instruction hint into detected agent configs (interactive only)
Installs the Archcore plugin on the hosts you selected

If no agents are detected in an interactive terminal, init prompts a multi-select of all supported agents plus a “Skip — configure later” option. In non-interactive contexts (no TTY), it installs nothing and prints a hint to run archcore mcp install --agent <id> later.

Re-running init prompts “Reinitialize?”. Confirming restores the directory and the host wiring and keeps the settings you already have: the sync mode, project id, language, and globals are preserved, and init prints Existing .archcore/settings.json kept. Only a project whose settings cannot be read at all falls back to the defaults. Declining leaves everything untouched. MCP and hook writes are always idempotent.

In non-interactive contexts (no TTY), init skips the instruction hint. Add it later with archcore instructions install.

Flags:

Flag	Description
`--agent <id>`	Non-interactive: initialize and install hooks, MCP config, the usage hint, and the plugin for the given agent id (e.g. `claude-code`, `cursor`, `codex-cli`, `copilot`). Repeatable.
`--project <path>`	Project root to initialize. Defaults to the current directory; env: `ARCHCORE_PROJECT_ROOT`.
`--yes`	Answer the reinitialize prompt with yes, and nothing else. Without `--agent`, the plugin step then prints the per-host install commands instead of running them.

Plugin delivery:

init also delivers the Archcore plugin, and an explicit host selection is the only thing that authorizes it.

The interactive picker marks every plugin-capable host with “also installs the Archcore plugin”. Codex CLI and GitHub Copilot are marked “machine-level, outside this project”, because their plugin stores have no repository scope. The screen states that a checked host is also the consent to install the plugin on it, and that nothing is installed for a host you leave unchecked.
Checking a host in that picker installs its plugin after wiring, with no second prompt.
--agent <id> carries the same consent for the hosts it names, interactive or not.
Detection is not consent. When the project already carries a host’s config (.claude/, .codex/, and so on), init wires that host, installs no plugin, and prints one hint naming archcore plugin install.
--yes without --agent, a session with no terminal, and any CI environment variable all produce the same result: init prints the per-host install commands and runs none of them.
A plugin delivery failure never changes init’s exit code.
Install is idempotent. A rerun over an installed plugin reports it and changes nothing.

See archcore plugin for the commands each host runs.

For a step-by-step walkthrough, see the CLI Quick Start.

archcore status

Check .archcore/ structure and document health.

archcore status [--project <path>]

Checks performed:

Directory structure exists
File naming follows <slug>.<type>.md pattern
Slugs are lowercase alphanumeric with hyphens only
Document types are valid (one of the 21 types)
YAML frontmatter has required title and status fields
Frontmatter is valid YAML
Tag hygiene: an invalid tag format is a failure, and a tag used only once is a warning (possible typo)
Sync manifest JSON structure
Orphaned relations (documents referenced but not on disk)
Global source health: any fatal state (missing, not a directory, unreadable, self-overlap, duplicate path) is a failure, an empty source is a warning, and a healthy source prints global source "<id>" (<N> document(s))

When status finds orphaned relations, it hints: “Run ‘archcore doctor —fix’ to remove orphaned relations”

Flags:

Flag	Description
`--project <path>`	Project root to check. Defaults to the current directory; env: `ARCHCORE_PROJECT_ROOT`.

archcore doctor

Full health check, with an optional fix pass.

archcore doctor [--fix] [--agent <id>] [--project <path>]

doctor runs every archcore status check, tag hygiene included, plus:

Verifies settings.json exists and is valid
Checks server reachability (if server URL is configured)
Reports whether each wired host can act on its hook config

If doctor finds any issue, it returns a non-zero exit code.

A host counts as wired only when its config file holds a hook command Archcore wrote. doctor skips a host that is detected but was never wired, and when no host is wired it says nothing about hooks rather than reporting them healthy. See archcore hooks for what the notes cover.

doctor also prints a one-line advisory when the update freshness cache already holds a newer version. The advisory makes no network call, never counts as an issue, and does not change the exit code. It still prints in a directory where Archcore was never initialized. See archcore update for what fills that cache.

Flags:

Flag	Description
`--fix`	Fix what can be fixed automatically (orphaned relations and host-wiring drift) before running the checks.
`--agent <id>`	With `--fix`: converge host wiring for the named agent only. Repeatable. Defaults to every auto-detected agent.
`--project <path>`	Project root to check.

--agent requires --fix. On its own it fails with --agent requires --fix.

doctor resolves the project root in order: the --project flag, then the ARCHCORE_PROJECT_ROOT environment variable, then the current working directory.

What --fix writes:

--fix writes to your agents’ config files, not just the manifest. It removes orphaned relations from the manifest, then converges host wiring by re-running the hook and MCP installers for each agent: a stale archcore hooks … command is rewritten in place, duplicate entries are healed, a drifted MCP entry is rewritten to its current shape, and the managed instruction block is refreshed. Fields Archcore does not own are preserved — the installers only touch what they wrote.

archcore doctor --fix                        # Every auto-detected agent
archcore doctor --fix --agent cursor         # One agent
archcore doctor --fix --agent cursor --agent claude-code   # Several

archcore config

Manage configuration.

archcore config                    # Show current sync type
archcore config get <key>          # Read a config value
archcore config set <key> <value>  # Set a config value

Available keys:

Key	Values	Description
`sync`	`none`, `cloud`, `on-prem`	Sync type. Read-only via `get`; `set` is locked
`project_id`	integer	Project ID for sync. Locked: `get` and `set` both return “not available yet”
`archcore_url`	URL	Server URL for on-prem. Locked: `get` and `set` both return “not available yet”
`language`	language code	Language for document content (e.g., `en`, `ru`)
`codeAlignment.sourceRoots`	comma-separated list	Source roots for the code-alignment advisory. `get` only; when the key is unset, `get` prints the defaults. Edit the value in `settings.json` by hand

Flags:

Flag	Description
`--project <path>`	Project root containing `.archcore/`. Defaults to the current directory; env: `ARCHCORE_PROJECT_ROOT`.

Examples:

archcore config set language ru
archcore config get language
archcore config get codeAlignment.sourceRoots

See Configuration for the default source roots and the validation rules.

archcore mcp

Run the MCP server or install MCP config.

archcore mcp              # Start stdio MCP server
archcore mcp install       # Install MCP config for all detected agents
archcore mcp install --agent <id>  # Install for a specific agent

Coding agents connect to this stdio server and launch it as a subprocess. You do not run it by hand.

Agent IDs: claude-code, cursor, copilot, gemini-cli, opencode, codex-cli, roo-code, cline

Flags:

Flag	Description
`--project <path>`	Project root to serve. Overrides the current directory.

archcore mcp resolves the project root in order: the --project flag, then the ARCHCORE_PROJECT_ROOT environment variable, then the current working directory. Use --project when an agent launches the server from a fixed location instead of the project directory.

60 seconds after it starts serving, archcore mcp runs one background update attempt on its own goroutine. The attempt writes nothing to stdout and never delays a JSON-RPC response. See unattended update for the conditions that must hold before anything is replaced.

See MCP server for details.

archcore instructions

Manage the “use Archcore” hint in agent instruction files.

The hint tells agents that Archcore’s MCP tools are available and when to consult them. Without it, agents may never call the MCP tools even though the server is installed.

archcore instructions install   # Write the hint into detected agent configs
archcore instructions remove    # Remove the hint

Subcommands:

Subcommand	Description
`install`	Writes the “use Archcore” hint into the instruction files of detected agents (`CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`).
`remove`	Removes the hint previously written by `instructions install` or `init`. Works even after the project is de-initialized.

Flags:

Flag	Description
`--agent <id>`	Target a single agent host (e.g. `claude-code`, `cursor`, `gemini-cli`, `codex-cli`) instead of all detected ones. Accepted by both subcommands; not repeatable, so the last value wins.
`--project <path>`	Project root to operate on. Accepted by both subcommands; `install` requires `.archcore/` there, `remove` does not.

Both subcommands resolve the project root in order: the --project flag, then the ARCHCORE_PROJECT_ROOT environment variable, then the current working directory.

Every target file (CLAUDE.md, AGENTS.md, GEMINI.md) receives the hint inside a managed marker block:

<!-- archcore:start -->
…
<!-- archcore:end -->

The marker block lets Archcore update or remove the hint without touching your own content. remove deletes only the marker block and leaves the rest of the file intact. A second write is idempotent, so the agents that share AGENTS.md collapse into a single block.

Instruction file locations:

Agent	Instruction file(s)
Claude Code	`CLAUDE.md` and `AGENTS.md`
Gemini CLI	`GEMINI.md`
Cursor, OpenCode, Codex CLI, Roo Code, Cline, GitHub Copilot	`AGENTS.md`

Claude Code gets both files. It reads CLAUDE.md natively and does not auto-read AGENTS.md, so CLAUDE.md carries the hint; the AGENTS.md block keeps the repository on the standard the other hosts converge on.

Examples:

archcore instructions install                       # All detected agents
archcore instructions install --agent claude-code   # Claude Code only
archcore instructions remove                        # Strip the hint from every target

archcore instructions remove --agent claude-code strips the CLAUDE.md block and deletes the legacy .claude/rules/archcore.md written by earlier CLI versions. That command leaves the shared AGENTS.md block to the AGENTS.md agents’ own remove. archcore instructions remove without --agent covers every target.

archcore hooks

Install agent hooks and serve hook events. Hooks intercept three host lifecycle events:

Event	What it does
`session-start`	Injects the project recap into a new session.
`pre-tool-use`	Blocks a direct write to an `.archcore/` document, and injects the documents that constrain the file being edited.
`post-tool-use`	Reports structure problems, relation cascades, and precision findings after a document mutation.

archcore hooks install                  # Every detected agent
archcore hooks install --agent cursor   # One agent only

install writes hooks for every detected agent, then installs the MCP config for those same agents.

Flags:

Flag	Description
`--agent <id>`	Install for a single agent. Not repeatable, so the last value wins.
`--project <path>`	Project root containing `.archcore/`.

archcore hooks resolves the project root in order: the --project flag, then the ARCHCORE_PROJECT_ROOT environment variable, then the current working directory.

Agent selection goes through --agent, never a positional argument. A mistyped archcore hooks install cursor is rejected instead of falling back to auto-detect.

After a successful install, the command prints notes on whether each host can run what was written. Silence means the wiring works.

Per-event commands (invoked by the host, not by you):

archcore hooks claude-code session-start
archcore hooks cursor pre-tool-use
archcore hooks copilot post-tool-use

Hosts with command leaves: claude-code, cursor, gemini-cli, copilot, codex-cli, opencode

Every leaf is hidden. An unrecognized host or event writes empty stdout and exits 0, because stdout is the hook protocol channel: anything else printed there would land in the agent’s context.

See Hooks for the full guard and advisory detail.

archcore plugin

Manage the Archcore plugin on the four hosts that ship one: Claude Code, Cursor, Codex CLI, and GitHub Copilot.

archcore plugin install [--agent <id>] [--project <path>] [--scope user|project]
archcore plugin update  [--agent <id>]
archcore plugin remove  [--agent <id>]
archcore plugin status  [--agent <id>]

Typing the verb is the consent for every host it targets, so each verb runs the same way with or without a terminal. This is the difference from archcore init, where consent comes from a checked host or an --agent flag.

Three frozen identifiers address the plugin everywhere: repository archcore-ai/plugin, marketplace archcore-plugins, plugin id archcore@archcore-plugins.

Flags:

Flag	Description
`--agent <id>`	Act on one host: `claude-code`, `cursor`, `codex-cli`, `copilot`. An agent with no shipping plugin fails with an error naming only those four ids. Defaults to every host that ships a plugin.
`--project <path>`	Project root containing `.archcore/`. Read by `install --scope project` only.
`--scope`	Which Claude Code settings file gains the marketplace entry: `user` or `project`. Accepted by `install` only; default `user`.

--scope project writes into the repository’s .claude/settings.json, and the CLI prints that the committed file delivers the declaration to every teammate who checks it out.

What install runs per host:

Host	Commands
Claude Code	`claude plugin marketplace add archcore-ai/plugin`, then `claude plugin install archcore@archcore-plugins` (user scope by default), then merges an `extraKnownMarketplaces["archcore-plugins"]` entry with `"autoUpdate": true` into `~/.claude/settings.json`, preserving unknown fields
Cursor	No CLI mechanism. The command prints the instruction to add the plugin from the Cursor UI (Marketplace or `/add-plugin`) and runs no host command
Codex CLI	`codex plugin marketplace add archcore-ai/plugin`, then `codex plugin add archcore@archcore-plugins` (machine-level)
GitHub Copilot	`copilot plugin install archcore-ai/plugin:plugins/archcore` (machine-level)

What update runs per host:

Host	Commands
Claude Code	`claude plugin marketplace update archcore-plugins`, then `claude plugin update archcore@archcore-plugins`
Cursor	Prints the Cursor UI instruction and runs no host command
Codex CLI	`codex plugin marketplace upgrade archcore-plugins`. Codex has no per-plugin update, so refreshing the marketplace snapshot is the update
GitHub Copilot	`copilot plugin update archcore@archcore-plugins`

How it decides what to do:

The CLI reads evidence in this order and stops at the first tier that answers:

The host CLI is on PATH. The CLI reads that host’s own read-only listing: claude plugin list --json, copilot plugin list, or codex plugin list --json. A mutating command runs only after that listing confirms the plugin.
The host CLI is absent. The CLI reads the host’s on-disk plugin registry.
Neither answers. The host is skipped silently.

Each host command is bounded at 30 seconds, and the whole step at 120 seconds. A failed or timed-out command prints the exact command that ran, and the run continues with the next host.

Exit codes and reporting:

archcore plugin status reports, per host, the evidence found, whether the plugin is present, and its version when the host reports one. It always exits 0.
A direct archcore plugin invocation exits non-zero when a host action it attempted failed. A host skipped for missing evidence does not fail it.
remove runs the host’s own uninstall and removes the autoUpdate entry the CLI wrote. When ~/.claude/settings.json is invalid JSON, remove reports it and stops without writing a backup, because rewriting the file fresh would discard content Archcore never wrote.
The plugin surface sends no telemetry and never attempts privilege elevation.

OpenCode, Gemini CLI, Roo Code, and Cline ship no Archcore plugin, so archcore plugin never addresses them.

For installing the plugin from a host’s own UI or CLI, see Install the plugin.

archcore update

Check for and install the latest version.

archcore update

Reads the latest release tag from the https://github.com/archcore-ai/cli/releases/latest redirect (not the GitHub API), compares versions, downloads the binary for your OS/architecture, verifies the checksum, and updates in place.

Flags:

Flag	Description
`--check`	Quietly report whether a newer version exists. Caches the result for 24 hours, uses a short network timeout, and always exits 0. Built for hooks and advisories.

Plugin update step:

After the binary phase, a typed archcore update refreshes the Archcore plugin on every host that already carries it.

The step runs after a replacement and after an already-current result. A failed binary phase skips it.
--check never runs it.
A host without the plugin produces no output.
The step never changes the exit code and sends no telemetry event.
archcore plugin update runs the same actions.

Unattended update in the background:

archcore mcp starts one background update attempt 60 seconds after it begins serving. Every condition below must hold, in this order, before anything is replaced:

The binary carries the official-build marker injected by the release workflow.
The running version is not dev.
No CI environment variable is set.
No other process holds the 24-hour claim for this binary path.
The install directory is writable by this process.
The latest version parses and is strictly newer.

Refusals at conditions 1 to 3 are silent. The running process keeps executing the image it started with, so the new version takes effect at the next launch: the next session, the next hook invocation, or the next command you type. When a replacement completes, one line goes to stderr, which lands in the host’s server log.

No environment variable disables unattended update. DO_NOT_TRACK and ARCHCORE_TELEMETRY_OPTOUT stop telemetry and leave updates working. Making the install directory root-owned is the supported way to stop a machine from updating itself.

Telemetry:

The update paths report three anonymous events: cli_updated, cli_update_failed carrying the failed stage, and cli_update_skipped carrying the skip reason. A trigger property separates a typed manual run from an auto one.

No event carries an error message, a path, a directory name, a user name, a host name, or repository data.
archcore update --check sends nothing.
When a manual event is delivered, archcore update prints one disclosure line naming the opt-out variable and https://archcore.ai/privacy.
A build without an injected key sends nothing.
Set DO_NOT_TRACK or ARCHCORE_TELEMETRY_OPTOUT to any value other than 0 to stop every event. These are the same two variables the analytics and opt-out section describes.

archcore —version

Display the current version.

archcore --version

archcore —help

Show help for every command.

archcore --help