> zforge CLI Reference
Complete command reference for the zforge CLI. Build, validate, test, and publish Agent Zero skills to the ZeroForge marketplace.
Install: pip install zforge · Full setup guide → · Auto-upgrades on every launch.
Onboarding
New to ZeroForge? Start here. Shows what to do next with a guided introduction to the CLI and marketplace.
Skill Creation
Scaffold a new Agent Zero skill with the correct folder structure, SKILL.md, skill.json, SkillTest.md, and a starter script.
| Argument | Required | Description |
|---|---|---|
| name | Yes | Skill folder name (use hyphens, e.g. my-skill) |
Run the APOL AI experiment pipeline to auto-generate and iteratively refine your SKILL.md using AI. Produces a high-quality skill description ready for certification.
Validation Pipeline
Validate skill metadata, folder structure, and SKILL.md completeness against ZeroForge quality standards. Returns a pass/fail with detailed output.
Run the full functional test suite: syntax checks, runtime smoke tests on scripts/main.py, and custom tests defined in SkillTest.md. Skills must pass to be certified.
🚀 Full automated pipeline in one command: scaffold → generate GOAL.md → APOL AI refinement → validate → test → publish. The fastest path from idea to live marketplace listing.
| Argument | Required | Description |
|---|---|---|
| name | Yes | Name of the skill to scaffold and build |
Authentication
Authenticate with ZeroForge via GitHub OAuth using PKCE (OAuth 2.1) — the same secure flow used by GitHub CLI and VS Code. Your access_token is never exposed in the browser URL or history. Your API key is fetched automatically and saved to ~/.zforge/config.json (permissions: 0o600 — owner-only). One-time setup — all future zforge publish commands use your stored credentials automatically. Use --manual to paste an API key instead.
| Flag | Description |
|---|---|
| --manual | Paste API key manually from zero-forge.org/profile/edit/ instead of browser OAuth |
Authenticate directly without a browser — ideal for headless servers, CI pipelines, and scripts. Saves your API key to ~/.zforge/config.json instantly without any prompts.
Get your API key at zero-forge.org/profile/edit/
One-off publish without saving credentials to disk. The env var takes priority over any stored config — useful for automated pipelines and ephemeral environments.
Display the currently authenticated GitHub handle. Reads from ~/.zforge/config.json or the ZFORGE_API_KEY environment variable. Use before publishing to confirm your session is active.
Publishing
Validate, APOL-certify, package, and upload a skill to the ZeroForge marketplace. Skills scoring ≥0.80 are auto-certified. Requires a ZeroForge account (GitHub OAuth).
Discovery & Installation
Download and install a skill from the ZeroForge marketplace into your Agent Zero skills folder by skill name or slug.
Install a skill AND immediately run it in one command. No Agent Zero setup required. Installs dependencies, executes the skill, and optionally cleans up after.
| Option | Required | Description |
|---|---|---|
| --args | No | Arguments to pass to the skill script |
| --output-dir | No | Where to install (temp dir by default) |
| --keep | No | Keep installed files after running |
Browse all approved skills on the ZeroForge marketplace directly in your terminal.
Search the ZeroForge marketplace by keyword. Returns matching approved skills with descriptions and install commands.
Utility
Show current CLI version, available commands, and system info. Also checks for updates (zforge auto-upgrades on every launch).