@startanaicompany/pluginz

Agent-side CLI for the pluginz plugin registry — discover and install Claude Code plugins inside any Node-based agent container.

Talks to a running pluginz server over HTTPS using a shared bearer token. Zero runtime config files — everything is environment variables.

Read-only by design. This CLI lets agents search and install plugins. It cannot push, modify, or delete entries in the registry — those flow through the admin console at tech.startanaicompany.com.

Install

npm install -g @startanaicompany/pluginz

Or, for one-off use without a global install:

npx @startanaicompany/pluginz list

Configuration

Set these in the agent container's environment:

| Variable | Required | Default | Purpose | |---|---|---|---| | PLUGINZ_API_URL | no | https://pluginz.startanaicompany.com | Base URL of the pluginz server. Override for staging/local. | | SAAC_AGENT_API_KEY | yes | — | The agent's ag_* api key — same one used for skillz/agentz/rolez/vizion. tech.saac validates it on the server's behalf. | | PLUGINZ_INSTALL_DIR | no | $HOME/.claude/plugins | Where installed plugins are extracted |

Usage

pluginz list                      # list all available plugins
pluginz list --keyword mcp        # filter by keyword
pluginz search "invoice"          # full-text search over name + description
pluginz show pdf                  # show metadata + all versions for a plugin
pluginz install pdf               # install latest version
pluginz install [email protected]         # install a specific version
pluginz installed                 # list locally installed plugins with versions + SHAs
pluginz update                    # update all installed plugins
pluginz update pdf                # update a single plugin
pluginz remove pdf                # remove a locally installed plugin

All list-style commands support --json for machine-readable output. The list/search output includes a capabilities tag (cmd, agent, hook, mcp, skill) so agents can see at a glance what each plugin contains.

How install works

1. GET /api/v1/plugins/{name}/download?version=<v> streams a tar.gz archive
2. The CLI sends Authorization: ApiKey $SAAC_AGENT_API_KEY; pluginz forwards that to tech.saac's MCP orchestrator for validation (cached 60s)
3. The response includes an X-Pluginz-SHA256 header; the CLI verifies the downloaded bytes against it before touching disk
4. The archive is extracted into $PLUGINZ_INSTALL_DIR/<plugin-name>/, stripping the top-level <plugin-name>/ prefix that the server adds during normalization
5. A .pluginz-manifest.json file is written into that directory with {name, version, sha256, installed_at} for use by installed, update, and remove
6. enabledPlugins["<plugin-name>"] = true is added (idempotently) to ~/.claude/settings.json so Claude Code actually picks the plugin up. Other keys in settings.json are preserved untouched. remove reverses this. Only happens when the install lands at the canonical ~/.claude/plugins/ — if you override PLUGINZ_INSTALL_DIR, the CLI prints a note that registration was skipped (Claude Code wouldn't find it there anyway).

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Usage error (bad args) | | 2 | Auth error (missing/invalid token) | | 3 | Not found (plugin or version) | | 4 | Network error | | 5 | Integrity error (SHA mismatch) |

Related

• pluginz server + agent Python CLI: https://github.com/Ryan-SAAS/pluginz
• Live registry: https://pluginz.startanaicompany.com/docs

License

MIT