ForgeCatCLI Reference
All available commands in the ForgeCat CLI.
This page reflects forgecat@0.3.2.
install
Install a profile from the registry, GitHub, or a local directory.
forgecat install [options] <source>Arguments:
source— Profile specifier (@user/name,@user/name@version,github:user/repo,./local)
Options:
-p, --platform <ids>— Target platform(s), comma-separated-f, --force— Force overwrite on conflicts-y, --yes— Auto-accept script and hook consent prompts (non-interactive). Does not bypass security gates--allow-high-risk— Install even if the security evaluation has high-risk findings (explicit consent;--allow-dangeris a deprecated alias)--allow-unevaluated— Install a version whose security evaluation has not finished yet (explicit consent)--no-lockfile— Skip lockfile update--dry-run— Preview without writing files--frozen— Error if lockfile is out of date (CI mode)--target-dir <path>— Home-target platforms (openclaw/hermes): install into this base dir instead of auto-resolving--target-agent <name>— OpenClaw: install into this agent's workspace (default: the default agent)--target-profile <name>— Hermes: install into this named profile's home (default: the active profile)
uninstall
Uninstall a profile.
forgecat uninstall [options] <profile-name>Arguments:
profile-name— Profile to uninstall
Options:
--force— Delete even locally modified files-p, --platform <id>— Home-target platform (openclaw/hermes): uninstall from its home base only-y, --yes— Auto-accept the home-cleanup confirmation--target-dir <path>— Home-target platforms: explicit base dir (mirrors install)--target-agent <name>— OpenClaw: agent whose workspace to clean--target-profile <name>— Hermes: named profile whose home to clean
update
Update installed profile(s) to the latest version from the registry.
forgecat update [options] [target]Arguments:
target— Profile to update (@user/nameor@user/name@version); omit to update all installed
Options:
-p, --platform <ids>— Target platform(s), comma-separated-f, --force— Force overwrite on conflicts-y, --yes— Auto-accept script and hook consent prompts (non-interactive). Does not bypass security gates--allow-high-risk— Update even if the security evaluation has high-risk findings (explicit consent;--allow-dangeris a deprecated alias)--allow-unevaluated— Update to a version whose security evaluation has not finished yet (explicit consent)--dry-run— Show what would change without writing files
init
Scaffold a new profile. Creates profile.yml, README.md, and .gitignore.
forgecat init [options] [dir]Arguments:
dir— Directory to initialize (default: current directory)
Options:
-y, --yes— Skip prompts, use defaults-f, --force— Overwrite existingprofile.yml--description <text>— Set description without prompting--scope <name>— Set scope (defaults to logged-in username)--with <list>— Comma-separated resource dirs to scaffold (agents,skills,rules,commands,hooks) orall
validate
Validate the local profile.yml: schema, name, declared files, hooks, and security checks. This command does not call the network.
forgecat validate [options]Options:
--strict— Treat warnings as errors (CI gate)--json— Emit machine-readable JSON to stdout--cwd <dir>— Run against a different directory
plan
Preview the install layout — what lands where, per platform. This command does not call the network and writes nothing.
forgecat plan [options]Options:
--json— Emit machine-readable JSON to stdout--cwd <dir>— Run against a different directory
scan
Find resource files on disk that are not declared in profile.yml.
forgecat scan [options]Options:
--track— Add the discovered resources toprofile.yml--json— Emit machine-readable JSON to stdout
track
Add discovered resources to profile.yml. By default this opens an interactive picker.
forgecat track [options]Options:
--all— Track every discovered resource without prompting--dry-run— Show what would be tracked without modifyingprofile.yml--json— Emit machine-readable JSON to stdout and bypass the interactive picker
list (alias: ls)
List installed profiles.
forgecat list [options]
forgecat ls [options]Options:
-v, --verbose— Show file-level details
status (alias: st)
Show file change status.
forgecat status [options] [profile-name]
forgecat st [options] [profile-name]Arguments:
profile-name— Specific profile to check
Options:
--json— JSON output
search
Search profiles on the hub. Omit the query to browse all profiles.
forgecat search [options] [query]Arguments:
query— Search query (omit to browse all profiles)
Options:
--platform <id>— Filter by platform--sort <field>— Sort bydownloadsorupdated--limit <n>— Max results per page (default: 20)
view
View profile details.
forgecat view <profile-name>Arguments:
profile-name— Profile to view (@scope/name)
push
Publish a profile to the registry. push sets the version for you: it reads the latest version on the registry and proposes the next one (patch by default, or pick patch/minor/major when prompted). A profile's first push starts at 0.1.0.
forgecat push [options]Options:
-y, --yes— Skip prompts (non-interactive); auto-detected when there's no TTY--bump <level>— Bump level for the auto version:patch(default),minor, ormajor--set-version <version>— Publish an exact version instead of the auto bump (rejected if it already exists; warns on downgrade)--visibility <level>— Set visibility:publicorprivate(required to publish a public profile non-interactively)--tags <list>— Seed tags on first push (comma/space separated)--json— Machine-readable JSON result on stdout (implies non-interactive)--registry <url>— Registry URL override--dry-run— Publish preview: runs auth, registry checks, and the security scan, but does not upload the tarball
Non-interactive / CI / agents: push runs non-interactively when --yes, --json, or no TTY is detected — no prompts are shown. Pass --bump, --visibility, and --tags to set values explicitly instead of falling back to defaults. Publishing a new profile as public, or flipping an existing profile from private to public, requires an explicit --visibility public — ForgeCat won't silently expose a profile.
clone
Download a published profile's source for editing. Owner-only.
forgecat clone [options] <profile>Arguments:
profile— Profile to clone (@scope/nameor@scope/name@version)
Options:
--out <dir>— Target directory (default: current directory)--force— Overwrite files that already exist in the target-y, --yes— Skip the write-consent prompt (non-interactive)--registry <url>— Registry URL override
pull
Refresh a cloned profile's source to the registry's latest version. Owner-only.
forgecat pull [options]Options:
--out <dir>— Directory holding the cloned profile (default: current directory)--force— Overwrite without confirmation-y, --yes— Skip the overwrite confirmation (non-interactive)--registry <url>— Registry URL override
unpublish
Unpublish a published profile — a single version or the full profile.
forgecat unpublish [options] <target>Arguments:
target— Profile (@scope/name) or a specific version (@scope/name@1.2.0)
Options:
-y, --yes— Skip the y/N confirm for a version unpublish (no effect on full unpublish)--force— Skip the name-typing confirm for a FULL unpublish (dangerous; CI rollback only)--registry <url>— Registry URL override
visibility
Set a published profile to public or private.
forgecat visibility [options] <profile> <visibility>Arguments:
profile— Profile name (@scope/name)visibility—publicorprivate
Options:
--registry <url>— Registry URL override
setup
Configure MCP server environment variables for installed profiles.
forgecat setup [options]Options:
--reconfigure— Re-prompt for all values, including already configured ones
tag
Manage profile tags.
forgecat tag <command>Commands:
list <profile>— List tags for a profileadd <profile> <tags...>— Add tags to a profileremove <profile> <tags...>— Remove tags from a profile
Shared option:
--registry <url>— Registry URL override
login
Login via Device Flow.
forgecat login [options]Options:
--registry <url>— Registry URL
logout
Logout and remove credentials.
forgecat logoutwhoami
Show current user.
forgecat whoami [options]Options:
--json— JSON output