AgentForge CLI 🤖⚒️

A powerful command-line interface to scaffold, manage, build, and deploy AI Agents and Skills for the GoClaw platform.

Note to Users: This README is intended for developers maintaining or contributing to the AgentForge CLI repository. If you are a user looking for instructions on how to use the CLI commands (Agent Management, Skill Management, Workspace Sync), simply run agentforge manual in your terminal after installation, or read the README.md generated inside your workspace after running agentforge init.

---

Installation & Local Development

Global Installation (Recommended)

You can install the AgentForge CLI globally directly from NPM:

npm install -g @innominatum/agentforge-cli

Local Development

Since you are modifying or maintaining the CLI source code, you should install and use it globally on your local machine using NPM's symlink feature:

1. Clone this repository and navigate to its folder.
2. Install the dependencies and compile the TypeScript code:

   npm install
   npm run build

3. Create a global symlink:

   npm link

   Now you can use the agentforge command anywhere on your computer, and it will run the code from this folder.

Development Workflow

Whenever you make changes to the source code in src/, you must compile the TypeScript code before the agentforge command reflects your changes:

npm run build

---

Repository Structure

agents-cli/
├── src/                 # TypeScript source code for all CLI commands
│   └── index.ts         # Main entry point and command definitions
├── templates/           # Default templates copied to user workspaces
│   ├── CLI_MANUAL.md    # The Single Source of Truth for user documentation
│   ├── default-agent/   # Boilerplate files for new agents
│   └── default-skill/   # Boilerplate files for new skills
├── documents/           # Reference documentation for internal use (e.g. GoClaw API)
├── dist/                # Compiled JavaScript output (generated by build)
├── package.json         # NPM metadata and dependencies
└── tsconfig.json        # TypeScript compiler configuration

---

Documentation Management

The user-facing documentation is centralized to ensure the CLI terminal output and the user's workspace README.md are always perfectly synchronized.

If you add a new command or change how the CLI works:

1. Open templates/CLI_MANUAL.md.
2. Update the documentation there.
3. The next time a user runs agentforge init, they will get the updated manual. If they run agentforge manual, the CLI will read directly from that template file.

---

NPM Publishing (Maintainers)

Manual Publishing

When this CLI is ready for a new release:

1. Update the version in package.json (e.g., from "1.0.1" to "1.0.2").
2. Run npm run build to ensure the dist/ directory is fully updated.
3. Login to your npm account using npm login.
4. Publish the package using npm publish --access public (you will be prompted for your 2FA security key).

Automated Publishing (Trusted Publishing / OIDC)

To fully automate your CI/CD pipeline securely without using any hardcoded NPM tokens or bypassing 2FA, NPM provides "Trusted Publishing" with GitHub Actions:

1. Go to the NPM website and navigate to the @innominatum/agentforge-cli package.
2. Go to Settings > Publishing Access.
3. Under Trusted Publishers, click Add Publisher > GitHub Actions.
4. Fill in the repository details:
   • GitHub Organization/User: Innominatum-pt
   • GitHub Repository: agentforge-cli
   • Workflow file (optional): publish.yml
5. Click Add Publisher.

Once configured, the .github/workflows/publish.yml workflow provided in this repository will automatically securely authenticate via OIDC and publish your package whenever you create a new GitHub Release.