§01reading material

Driving the CLI

CLI instructions, I dare you to read them this time.

edition§01
classprimer / cli
revised2026-05-30
codexv0.1 · public draft

who you are

Sign in, sign out, who are you?

npx @aipkgs/cli login                           # opens an auth flow in the browser
npx @aipkgs/cli logout                          # revokes the current session
npx @aipkgs/cli whoami                          # show the signed-in account

If you have an api token you can set it with AIPKG_TOKEN=<token> env var.

No token, no publishing.

start a package

Init

init writes a fresh aipkg.json in the current directory.

npx @aipkgs/cli init                            # scaffold aipkg.json in cwd
npx @aipkgs/cli set target claude               # your default agent target

The target decides where files land on install: .claude/ for claude, .codex/ for codex.

pull the deps

Installing packages

npx @aipkgs/cli install reads every dep in aipkg.json, verifies each SHA against aipkg.lock, and writes the files into place. Point it at another manifest with -m, --manifest <path>.

npx @aipkgs/cli install                         # install every dep in aipkg.json
npx @aipkgs/cli install -m ./other/aipkg.json   # use a manifest elsewhere

# add a single asset by type
npx @aipkgs/cli skill    acme/code-review       # a skill
npx @aipkgs/cli agent    acme/reviewer          # a sub-agent
npx @aipkgs/cli rule     acme/style-guide       # a rule
npx @aipkgs/cli setup    acme/status-line       # a setup
npx @aipkgs/cli box      acme/starter           # a box (bundle of assets)

# org-scoped sub-namespace — three segments
npx @aipkgs/cli skill forge/duck/frontend-design

The ref is <org>/<slug> or <org>/<key>/<slug>. The <key> segment is optional — use it when the publisher namespaces under their org.

The lockfile memorizes the version and sha.

undo an install

Remove a single asset

Every package type takes a remove subcommand. Pass the full ref.

npx @aipkgs/cli skill    remove acme/code-review
npx @aipkgs/cli agent    remove acme/reviewer
npx @aipkgs/cli rule     remove acme/style-guide
npx @aipkgs/cli setup    remove acme/status-line
npx @aipkgs/cli box      remove acme/starter

wire in a server

MCP servers — http or stdio

An MCP server is either an HTTP endpoint or a local process. Pick one. Pass --url for HTTP or --command for stdio.

# http server — headers allowed, env not
npx @aipkgs/cli mcp add my-api --url https://mcp.example.com \
  --header "Authorization=Bearer $TOKEN" \
  --header "X-Workspace=acme"

# stdio server — args and env allowed, headers not
npx @aipkgs/cli mcp add local-fs --command node \
  --arg ./mcp-server.js \
  --arg --root=/tmp \
  --env LOG_LEVEL=debug

npx @aipkgs/cli mcp remove my-api               # drops it from aipkg.json, .lock, .mcp.json

--arg, --header, and --env are all repeatable. The CLI writes the server into aipkg.json, locks it in aipkg.lock, and emits a matching entry in .mcp.json for the agent to read.

The MCP entries become deps when you publish. You can ship MCP config with you package.

ship it

Publish whatever is in the directory

publish reads the aipkg.json manifest and publishes the assets in the targe directory.

npx @aipkgs/cli publish                         # publish the box in cwd
npx @aipkgs/cli publish ./packages/my-skill     # publish a different directory
npx @aipkgs/cli publish --dry                   # print manifest + contents, no upload
npx @aipkgs/cli publish -y                      # skip the confirmation prompt

The version is sourced from the aipkg.json manifest. Bump the version field before you publish. The registry rejects duplicate versions.

one page

Cheat sheet

# auth
npx @aipkgs/cli login                           # sign in (opens browser)
npx @aipkgs/cli logout                          # revoke local token
npx @aipkgs/cli whoami                          # show current account

# scaffold
npx @aipkgs/cli init                            # write aipkg.json in cwd
npx @aipkgs/cli set target claude               # claude target (or codex)

# install — types: skill agent rule setup box
npx @aipkgs/cli install                         # install every dep in aipkg.json
npx @aipkgs/cli install -m <path>               # install from another manifest
npx @aipkgs/cli <type> <org>/<slug>             # add a single asset
npx @aipkgs/cli <type> <org>/<key>/<slug>       # org-scoped sub-namespace

# remove (by ref)
npx @aipkgs/cli <type> remove <org>/<slug>

# mcp
npx @aipkgs/cli mcp add <slug> --url <url>      # http server
npx @aipkgs/cli mcp add <slug> --command <cmd>  # stdio server
npx @aipkgs/cli mcp add <slug> --url <url> --header k=v
npx @aipkgs/cli mcp add <slug> --command <cmd> --arg <v> --env k=v
npx @aipkgs/cli mcp remove <slug>

# publish
npx @aipkgs/cli publish [dir]                   # ship the box in [dir] or cwd
npx @aipkgs/cli publish --dry                   # preview without uploading
npx @aipkgs/cli publish -y                      # skip confirmation

# meta
npx @aipkgs/cli --version
npx @aipkgs/cli --help