Skip to content

Publishing to InitHub

1. Sign in

Authenticate the CLI with your InitHub account:

initrunner login

The CLI opens your browser to sign in with GitHub and confirm a one-time code. Once you approve, your token is saved automatically.

For CI or headless environments, pass a token directly:

initrunner login --token YOUR_TOKEN

Verify your session with initrunner whoami. Create tokens at hub.initrunner.ai/settings with publish and read scopes.

2. Publish

Run from your agent directory. The CLI bundles the role and any referenced skills, schemas, and data files automatically:

# From your agent directory:
initrunner publish

# With a README (recommended):
initrunner publish --readme README.md

# With categories:
initrunner publish --category code-assistant

# Link to your source repo:
initrunner publish --readme README.md --repo-url https://github.com/you/my-agent

Without --readme, the package page only shows the description from your role metadata.

3. Share

Others can install your package with:

initrunner install your-username/my-agent

Pin to a specific version with your-username/my-agent@1.0.0. After installing, run it by name:

initrunner run my-agent

4. Update

Bump the version in your role.yaml and run initrunner publish again. Each version is immutable once published.

Reference

Package naming

Slugs must match [a-z0-9][a-z0-9-]*[a-z0-9] — lowercase letters, digits, and hyphens only. Names are globally unique and derived from metadata.name in your role file.

Categories

Pass --category <slug> one or more times to categorize your package. Browse available categories for valid slugs. If you misspell one, the publish still succeeds but the response includes unmatched_categories.

Yanking

Yank a broken version to hide it from latest resolution. Yanked versions remain downloadable with an exact version pin.

Security scanning

Every published version is automatically scanned for security risks. The scanner inspects tool configurations in your role YAML and skill frontmatter, checking for capabilities like custom code execution, shell access, MCP subprocess commands, unrestricted HTTP access, broad filesystem permissions, and privileged Docker settings.

Results appear as a badge on your package page:

  • Verified — no issues found
  • Warnings — potentially risky capabilities detected (e.g. MCP tools, unconfirmed Python execution)
  • Critical — high-risk capabilities detected (e.g. custom tool modules, shell tools, privileged Docker)

Scanning is informational and does not block publishing. Users can view the full list of findings on the package detail and version detail pages.

Troubleshooting

  • "Bundle missing manifest.json" — The archive must contain a manifest.json at the root. This is generated automatically by initrunner publish.
  • "Invalid package name" — metadata.name must be lowercase alphanumeric with optional hyphens (e.g., my-agent).
  • "Version X already exists" — Each version is immutable. Bump the version number to publish a new release.
  • "Integrity check failed" — A file's SHA-256 doesn't match the manifest. Re-run initrunner publish to regenerate the bundle.
  • "Invalid manifest" — Schema errors in manifest.json. Ensure you're using a compatible version of InitRunner.

See the InitRunner docs for the full CLI reference.