@getagents/cli

Command-line client for the GetAgents marketplace.

• Buyers install purchased Claude Code plugins, skills, agents, and MCP servers.
• Sellers validate and publish products.

Status: in active development against the walking-skeleton API. Not yet on npm. See docs/cli/design.md for the binding design and tickets #019–#025 for the implementation slices.

Local install

cd cli-command
npm install
npm run build
npm link            # makes the `getagents` binary available globally

Iterate without rebuilding

tsx is in devDependencies. Run the TypeScript source directly, no dist/ build between edits:

cd cli-command
npx tsx src/bin/getagents.ts --help

Same code path the linked binary uses, useful while modifying CLI source.

Pointing the CLI at local dev

For a round trip against your docker-compose API instead of production, source the activation script:

source cli-command/scripts/dev-env.sh

It sets:

• GETAGENTS_API_URL=http://localhost — your local Laravel API.
• GETAGENTS_CONFIG_DIR=$HOME/.config/getagents-local — a separate vault so the dev session doesn't touch your prod auth or installed products.

Inside the activated session:

• getagents-dev-status — show current env + auth state.
• getagents-dev-deactivate — restore the env you had before; your prod credentials become active again.

Override the defaults by exporting GETAGENTS_DEV_API_URL or GETAGENTS_DEV_CONFIG_DIR before sourcing. For a deeper walkthrough including seeded test fixtures, see the local development runbook.

Commands

| Command | Purpose | |---|---| | getagents auth login | Device-code sign-in. Prompts a verification URL + code; polls until confirmed. | | getagents auth logout | Revoke this machine's token and clear local credentials. | | getagents auth status | Show signed-in account, machine name, days until expiry. | | getagents sync | Reconcile the local vault against your entitlements. Idempotent. | | getagents install <slug> | Pull a purchased product into the vault and (for plugins) tell Claude Code about it. | | getagents uninstall <slug> | Remove a product from the vault. | | getagents list [--json] | Show installed products. | | getagents update [<slug>] | Update one or all installed products. | | getagents validate [--path <dir>] [--strict] | Schema + structure check against a product directory. | | getagents publish [--path <dir>] [--dry-run] | Validate, bundle, upload to GetAgents. | | getagents init [--non-interactive --config <file>] | Scaffold a new product directory. |

Global flags (root command, before subcommands):

• --json — line-delimited JSON envelopes to stdout. No ANSI, no spinners.
• --no-color — strip ANSI. NO_COLOR env var is also honoured.
• --verbose — log API requests/responses to stderr (Authorization redacted).
• --vault-dir <path> — override the config dir (default: $XDG_CONFIG_HOME/getagents). For tests and air-gapped users.

Vault layout

~/.config/getagents/                       chmod 0700
  local.vault/                             chmod 0700, registered with Claude Code
    .claude-plugin/marketplace.json
    plugins/<slug>/   skills/<slug>/   agents/<slug>/   mcp/<slug>/
  manifest.lock                            authoritative install state
  entitlements.json                        last server snapshot
  auth                                     bearer token, chmod 0600
  install-id                               per-machine UUID, chmod 0600

Tests

npm test                  # Vitest unit suite, no external deps
npm run test:integration  # Needs GETAGENTS_API_URL + Laravel app at APP_ENV=testing
npm run typecheck         # tsc strict
npm run lint              # eslint + prettier

Integration tests require:

1. A Laravel app running with APP_ENV=testing (so the test-only POST /test/confirm-device route is registered).
2. The CliFixturesSeeder seeded so [email protected] exists.
3. Either GETAGENTS_API_URL set to its base URL, or RUN_INTEGRATION=1.

CI bootstraps both — see .github/workflows/e2e.yml.

Layout

src/
  bin/getagents.ts            entry, parses argv
  cli.ts                      commander + global flags + error handling
  commands/                   one file per user-facing subcommand
  api/                        fetch wrapper + response types
  config/                     XDG paths, auth file, install id
  vault/                      atomic writes, lockfile, marketplace.json,
                              tar extract, watermarking, Claude Code shim
  sync/                       sync engine
  manifest/                   schema + offline validator + structure
  bundle/                     tar.gz builder
  output/                     human + JSON output
  util/                       errors, claude-version detection
tests/
  unit/                       fast, no-network
  integration/                hits a real Laravel app
  e2e/shims/claude            bash shim used by CI E2E to stand in for Claude Code
scripts/
  copy-assets.js              postbuild — copies schema.json into dist/
  sync-schema.js              fetches the live API schema and overwrites
                              src/manifest/schema.json (CI freshness gate)
  dev-env.sh                  source to flip the CLI to localhost API +
                              a separate vault dir; defines deactivate fn

Conventions

CLI conventions live in the project CLAUDE.md. Highlights:

• Every command supports --json mode via Logger.jsonEvent().
• Tests that touch the config dir always call setConfigDirOverride() first.
• API calls go through ApiClient so install_id and Claude-version headers are always set.