CLI · Level 3

Tools

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

Level 3 CLI tools support workspace operations, structural inspections, and state updates. These tools are independent of the daily build lifecycle.

Source Code Operations

Command Impl

# `search`

Executes full-text search across MDX sources. Returns file paths, line numbers, columns, and preview strings of matches.

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

Flags

Name	Type	Default	Description
`<query>` required	`string`		Search target. Supports plain text or regular expressions.
`--json`	`flag`		Output in machine-readable JSON format.
`--scope`	`string`	`"content"`	Specifies search scope. `content` (MDX body only) or `all` (includes frontmatter and metadata).
`--case-sensitive`	`flag`		Forces case-sensitive search. Case-insensitive by default.

Example: JSON Search

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

Command Impl

# `replace`

Executes batch string replacement operations across MDX sources. Default mode is read-only preview.

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

Flags

Name	Type	Default	Description
`<from>` required	`string`		Target string or regular expression to search for.
`<to>` required	`string`		Replacement string.
`--apply`	`flag`		Applies changes and writes to files. If not provided, only a preview is output.
`--scope`	`string`	`"content"`	Same scope setting as the `search` command.
`--include-code`	`flag`		Expands replacement scope to fenced code blocks. Skipped by default to prevent accidental code changes.
`--case-sensitive`	`flag`		Forces case-sensitive search.
`--json`	`flag`		Output in machine-readable JSON format.

Example: Execute Replacement

open-press replace . "old phrase" "new phrase" --apply

Render Inspection

Command Impl

# `inspect`

Executes post-build introspection. Invokes headless Chrome to analyze block geometry dimensions and comment markers of the built project.

open-press inspect . [--json]

Flags

Name	Type	Default	Description
`--json`	`flag`		Output in machine-readable JSON format.
`--no-build`	`flag`		Bypasses the build phase, analyzing the existing `dist-react/` directory.
`--host`	`string`	`"127.0.0.1"`	Server IP for headless Chrome to connect to.
`--port`	`string`	`"5186"`	Server port for headless Chrome to connect to.
`--dry-run`	`flag`		Outputs execution chain commands only, without starting the server or invoking Chrome.

Environment and State Management

Command Impl

# `doctor`

Reports workspace dependencies and package version status. Checks framework version and agent skills. Results cached for 24 hours.

open-press doctor .

Flags

Name	Type	Default	Description
`--json`	`flag`		Output in machine-readable JSON format.
`--no-cache`	`flag`		Bypasses local cache to query the latest information directly from npm.

The doctor command exit code is always 0. Automation flows should parse report.stale or report.coreUpdateAvailable from the JSON output to determine execution logic.

Command Impl

# `upgrade`

Upgrades workspace dependencies and agent skills. Use the `openpress-upgrade` skill for source migration and QA.

open-press upgrade .

Use with doctor; ensure a Git version control snapshot is created before execution. This command refreshes packages and skills, but workspace source migration is agent-owned: use openpress-upgrade to read applicable migration docs, scan press/, apply confirmed source edits, and loop through Migration QA checkpoints.

Command Impl

# `skills:sync`

Synchronizes skill packages to the .agents/skills/ directory and related platform mirrors. Executes updates based on skills-lock.json.

open-press skills:sync .

Flags

Name	Type	Default	Description
`--source`	`string`		Adds and installs a specific skill package. Format: `owner/repo` or `github:owner/repo`.
`--dry-run`	`flag`		Only prints the underlying `npx skills` command, does not execute installation.