Working with the CLI

The open-forge command helps you inspect your project's context and maintain its Markdown files. Choose a task below. The command reference defines every operation and option, and Everyday flows gives complete procedures. For a first walkthrough, use the ten-minute guide.

Start with these commands

When you want to	Run
Read startup context	open-forge context
Find a rule	open-forge find --tag Directive
Check links and navigation	open-forge doctor
Preview navigation updates after editing files	open-forge index --dry-run

The first three only read files. Review the Index preview, then run open-forge index to fill missing metadata and update generated Entries, the lists that help agents find files. These are maintenance tools, not required steps before every task.

After renaming or moving files by hand, preview open-forge repair --automatic --dry-run. Repair fixes proven links and affected Entries. When Git retains the old file's committed content, Index and Repair work in either order. Without Git, run Repair first while old Entries still record the file's metadata. Follow Doctor's next step for any remaining choice or edit.

Use open-forge --help for the installed command inventory and open-forge <command> --help for immediate syntax and common examples. Root help starts with an Essentials preview and installation. Command help puts examples before its behavior notes and options.

Which command for which job

Task	Command reference
Catch up after creating, renaming, or moving files by hand	After you edit files by hand
Inspect the workspace	status, route list, route inspect
Read and discover context	context, find, references
Add and organize knowledge	route init, route create, route update, route move, route remove
Check and repair	index, doctor, repair, cleanup
Install, update, or remove Framework content	install, update, remove
Manage optional Extension packages	extension list, extension inspect, extension create, extension install, extension update, extension remove
Share files through a Library	library list, library inspect, library attach, library sync, library detach

A source can be named by an ID such as guidance or an exact .agents path. See source references when selecting a target. To restore one left-out built-in category, preview open-forge route init <category> --framework --dry-run, review it, then run the same request without --dry-run. Use open-forge install --configure as the interactive way to change several setup choices.

Index and Repair preserve protected sources, including managed files and native Skill packages. Doctor names the managing Update or required edit. If Git times out, follow the retry command before deciding that a missing file was deleted. See manual edits.

Everyday habits

Preview each mutation with --dry-run, review its complete plan, then apply the same request. Check what changed and follow the result's next step. A dry run changes no files. Commands that need confirmation accept --automatic for unattended application. Route Init, Create, Update, Move, Index, and Cleanup apply directly. See prompts and unattended runs.

Use --workspace <path> to select another exact directory and --detail standard for reasons. The global options define shared flags.

For agents and scripts

For an initial context batch that includes the shipped CLI Skill, run open-forge context skills/open-forge-cli. Supply every known working file, including planned files, with repeated --for <path>. Follow explicit read instructions in the returned files. The Skill holds offline command-selection and result-handling guidance. The Context reference defines file conditions, pending context, and later batches.

Use --format json and check the exit code in scripts. 0 means completed and 2 means completed with warnings. The status and exit reference defines every result. Doctor returns a nonzero code for warnings or errors, so it can check workspace health in CI.

When an Extension or Library asks to change paths outside .agents, key mode starts focused on Allow once. Enter approves only this run without saving a grant. The numbered order stays 1. Allow always, 2. Allow once, 3. Cancel. Choose Allow always deliberately to save a grant for later operations. Line mode accepts always, once, or cancel, and an empty line cancels.

Next: Everyday flows.