CLI · Tier 3

Tools

Utilities for AI agents, the workbench, and debugging — search, replace, inspect, doctor, upgrade, skills:sync. These are implemented commands, but they are not part of the everyday build loop.

Tier 3 covers what agents need to operate on a workspace beyond the build lifecycle — locating content, applying bulk edits, reading post-render geometry, checking the workspace's freshness against upstream. Every entry on this page is marked Impl because it exists in open-press today.

Source — search and replace

Command Impl

# `search`

Full-text search across registered MDX sources. Returns file, line, column, and matched preview for each hit. Used by agents to locate content before editing — the workbench's find UI calls this too.

open-press search . <query> [--json]

Flags

Name	Type	Default	Description
`<query>` required	`string`		Plain text or regex pattern.
`--json`	`flag`		Emit machine-readable JSON instead of formatted output.
`--scope`	`string`	`"content"`	`content` = MDX body only; `all` = include frontmatter and metadata fields.
`--case-sensitive`	`flag`		Match case literally (default is case-insensitive).

Find every figure caption

open-press search . "Figure" --json | jq '.matches[] | {file: .path, line, preview}'

Command Impl

# `replace`

Search and replace across MDX sources. Previews by default — pass --apply to write. Agents use this for bulk edits without re-implementing source diffs.

open-press replace . <from> <to> [--apply]

Flags

Name	Type	Default	Description
`<from>` required	`string`		Source string or regex.
`<to>` required	`string`		Replacement text.
`--apply`	`flag`		Write changes. Without this flag, the command only previews — safe to run repeatedly.
`--scope`	`string`	`"content"`	Same semantics as search.
`--include-code`	`flag`		Also replace inside fenced code blocks (skipped by default to protect snippets).
`--case-sensitive`	`flag`		Match case literally.
`--json`	`flag`		Emit JSON report — required for agent consumption.

Preview, then apply

open-press replace . "old phrase" "new phrase"
# review the diff report

open-press replace . "old phrase" "new phrase" --apply
# writes the changes

Render — inspect post-build state

Command Impl

# `inspect`

Post-render introspection. Builds the workspace, launches headless Chrome against the static server, and reports block geometry / comment markers / TOC chain output. Used by the workbench inspector and by agents that need ground-truth layout data.

open-press inspect . [--json]

Flags

Name	Type	Default	Description
`--json`	`flag`		Emit JSON report. Required for agent consumption.
`--no-build`	`flag`		Reuse the existing `dist-react/` build instead of re-rendering.
`--host`	`string`	`"127.0.0.1"`	Static server host for the headless Chrome session.
`--port`	`string`	`"5186"`	Static server port.
`--dry-run`	`flag`		Print the underlying command chain (render → static-server → Chrome) without running.

inspect vs validate. validate is source-level (config / source references / link integrity); inspect is post-render (actual block positions after pagination). Both are legitimate — use validate for fast preflight, inspect when an agent needs to know how the page actually paginated.

Environment — workspace freshness

Command Impl

# `doctor`

Workspace freshness check. Reads the installed @open-press/core version, fetches the latest from npm, lists installed agent skills under .agents/skills/, and reports any pending migration notes in docs/migrations/. Cached for 24h in .openpress/cache/doctor.json.

open-press doctor .

Flags

Name	Type	Default	Description
`--json`	`flag`		Emit JSON report — required for agent / CI consumption.
`--no-cache`	`flag`		Bypass the 24h cache and re-fetch from npm.

Exit code is always 0 — doctor is informational, not a gate. CI scripts and agents should inspect report.stale or report.coreUpdateAvailable from the JSON output to decide whether to block.

Sample human output

○ open-press doctor

framework
  ⚠ @open-press/core: 0.7.1 installed → 0.8.0 available

skills
  ✓ 3 skills installed
    source: quan0715/open-press
    refresh: npx skills upgrade

migrations
  ⚠ 1 migration note(s) since your version:
    - docs/migrations/0.8.0.md

next
  npx open-press upgrade        # apply all updates (agent-driven)
  npx open-press doctor --json  # machine-readable output

Command Impl

# `upgrade`

Migrate a workspace to the current framework version. Updates package dependencies, refreshes skills, and applies version-specific migration scripts referenced in docs/migrations/. Alias: migrate.

open-press upgrade .

Pair with doctor: doctor identifies what needs updating; upgrade actually writes the changes. Always run git status first — upgrade modifies package versions, installed skills, and migration-targeted workspace files.

Command Impl

# `skills:sync`

Sync .agents/skills/ (and the per-platform mirrors under .claude/, .cursor/, .codex/, …) from the workspace's installed skill packs. Refreshes everything in skills-lock.json to its latest published version.

open-press skills:sync .

Flags

Name	Type	Default	Description
`--source`	`string`		Optional. Add an extra pack on top of the existing installation. Format: `owner/repo` or `github:owner/repo`.
`--dry-run`	`flag`		Print the underlying `npx skills` commands without executing.

If skills-lock.json is missing (e.g. workspace was scaffolded before skills:sync existed), the command performs a first-time install of the OpenPress framework skill bundle (quan0715/open-press).