CLI Reference

Commands & Options

The commands and flags exposed by the Codex Kit CLI.

Codex Kit keeps the CLI surface focused: scaffold a repo, update managed files, inspect status, and manage local Codex skills.

The CLI entrypoint is exposed through the codex-kit binary.

Primary Commands

codex-kit init
codex-kit install
codex-kit install --target plugin
codex-kit install --target mcp
codex-kit install --target skills
codex-kit install --target skills --scope local
codex-kit update
codex-kit sync --target mcp
codex-kit sync --target plugin
codex-kit sync --target skills
codex-kit sync --target skills --scope local
codex-kit list --target skills
codex-kit list --target skills --query frontend
codex-kit list --target skills --scope local
codex-kit list --target plugin
codex-kit list --target mcp
codex-kit remove --target skills --scope local --skills clean-code,planning
codex-kit setup-codex
codex-kit sync-codex
codex-kit status

What Each Command Does

init installs the full Codex Kit scaffold into the current project.
install without --target behaves the same as init.
install --target plugin installs only the workspace plugin into the current project.
install --target mcp installs the shipped MCP bundle into the current project's .codex/config.toml.
install --target skills installs only the shipped project skill bundle into .agents/skills and .agents/.shared.
install --target skills --scope local installs shipped skills into ${CODEX_HOME:-~/.codex}/skills for local Codex.
update refreshes scaffold-managed project files and keeps local modifications safe unless you pass --force.
sync --target mcp refreshes the shipped MCP bundle in the current project's .codex/config.toml.
sync --target plugin refreshes only the workspace plugin files in the current project.
sync --target skills refreshes only the project-local skill bundle in the current repository.
sync --target skills --scope local overwrites the local Codex copy with the current shipped skill version.
list --target skills shows the shipped skill catalog grouped by category.
list --target skills --query <text> searches the shipped skill catalog by keyword or domain.
list --target skills --scope local shows which shipped skills are already installed in local Codex.
list --target plugin reports workspace plugin status for the current project.
list --target mcp reports whether the shipped MCP bundle is installed in the current project or local Codex config.
remove --target skills --scope local --skills ... removes only the named local Codex skills.
setup-codex combines workspace plugin setup with local skill installation and prints next steps.
sync-codex combines workspace plugin sync with local skill sync after upgrading Codex Kit.
status reports missing, modified, and outdated scaffold-managed files in the current project.

Legacy Aliases

codex-kit sync --target project
codex-kit install --target project
codex-kit list-skills
codex-kit search-skills frontend
codex-kit list-installed-skills
codex-kit install-skills
codex-kit sync-skills
codex-kit remove-skills --skills clean-code,planning

Options

codex-kit init --path ./my-project
codex-kit install --path ./my-project
codex-kit init --force
codex-kit install --force
codex-kit init --dry-run
codex-kit install --dry-run
codex-kit init --install-plugin
codex-kit init --quiet
codex-kit install --target plugin
codex-kit install --target mcp
codex-kit install --target skills
codex-kit install --target mcp --scope local
codex-kit sync --target mcp
codex-kit sync --target skills --force
codex-kit sync --target plugin --force
codex-kit list --target plugin
codex-kit list --target mcp

codex-kit setup-codex --path ./my-project
codex-kit setup-codex --codex-home ~/.codex
codex-kit setup-codex --skills clean-code,planning
codex-kit sync-codex
codex-kit sync-codex --skills clean-code,planning

codex-kit list --target skills
codex-kit list --target skills --skills clean-code,planning
codex-kit list --target skills --query frontend
codex-kit list --target skills --scope local
codex-kit list --target skills --scope local --codex-home ~/.codex

codex-kit update --path ./my-project
codex-kit update --force
codex-kit update --dry-run
codex-kit update --install-plugin

codex-kit install --target skills --scope local --codex-home ~/.codex
codex-kit install --target skills --scope local --skills clean-code,planning
codex-kit install --target skills --scope local --force
codex-kit sync --target skills --scope local --skills clean-code,planning
codex-kit remove --target skills --scope local --skills clean-code,planning

codex-kit status --path ./my-project

Scope And Flags

Use project scope by default for scaffold, plugin, and project skill operations in the current repository.
Use project scope by default for scaffold, plugin, project skills, and project MCP operations in the current repository.
Use --scope local only when you want Codex Kit to write into ${CODEX_HOME:-~/.codex}.
Use --codex-home to target a different local Codex directory.
Use --skills only for targeted local skill install, sync, or removal.
Use --query only with list --target skills when searching the shipped skill catalog.
The shipped MCP bundle includes context7 and a commented mysql example wired for @benborla29/mcp-server-mysql; uncomment it only when you intentionally want to enable MySQL MCP.
Use --force when you intentionally want to overwrite existing or locally modified managed files.
Use --dry-run to preview what Codex Kit would write before changing files.

Managed File Behavior

The .codex-kit/manifest.json file tracks the path, template hash, installed hash, and install version for kit-managed files.

That data powers status, safe update, and detection of missing or locally modified managed files.