AgentPM™

publish#

Validate and package your tool/agent, then upload the signed artifact to the registry.

Overview#

agentpm publish runs the same validations as lint, packages your project into a .tar.gz, and (unless --dry-run) uploads it to the registry.

Command synopsis#

agentpm publish [--manifest <path>] [--schema <URL|PATH>] [--strict] [--dry-run] [--quiet] [--sign] [--key-id <KEY_ID>] [--token <PAT>]

Arguments#

  • --manifest <path> (default: agent.json). Path to the manifest to package and publish.
  • --schema <URL|PATH>. Override schema URL/path (same behavior as lint).
  • --strict. Treat warnings as errors (same semantics as lint).
  • --dry-run. Validate and package, but do not upload. Writes a local artifact.
  • --quiet. Suppress progress output (auto-enabled when not a TTY).
  • --sign — Attach an author signature using a local key (namespace must allow/require). Prompts for the key’s passphrase.
  • --key-id <KEY_ID> — Key to use when --sign (from agentpm keys list). Required if --sign is set.
  • --token <PAT> (env: AGENTPM_TOKEN). Personal Access Token for headless auth (overrides env/file).
Validation

publish runs lint automatically. Any lint errors will block publish; with --strict, warnings also block publish

Token resolution order

flag (--token) > env (AGENTPM_TOKEN) > token file (written by agentpm login).

Authentication required#

You must be logged in to publish. Any of these methods work:

  • Flag: agentpm publish --token "$AGENTPM_TOKEN"
  • Env var: AGENTPM_TOKEN (e.g., export AGENTPM_TOKEN=…)
  • Logged-in session: run agentpm login once to create a local token file

Namespace required#

Before publishing, you need a namespace.

  • Create it on your profile at the AgentPM site.
  • Once created, your namespace is automatically applied to any published tools.
  • The namespace is linked to your PAT (Personal Access Token), so publishing uses the namespace associated with the token’s account.
New here?

Create an account by signing in at https://agentpackagemanager.com/signUp , then authenticate via agentpm login. You can verify auth anytime with agentpm whoami.

Signing (author & registry)#

  • Author-sign at publish with your local key:
agentpm publish --sign --key-id <KEY_ID_FROM_keys_list >
# prompts for key passphrase
  • Registry attestation happens automatically for every publish.

Requirements#

  • Your namespace’s signing mode controls author signatures: off | optional | required (set on the website, Profile → Namespaces → Manage).
  • If required, publish will fail unless at least one valid author signature is attached and the key is registered to the namespace:
Error: HTTP 422: signature_required: namespace requires at least 1 valid author signature

Helpful commands#

  • Manage local keys: agentpm keys generate|list|export
  • Register key with namespace: agentpm namespace add-signer --namespace <ns> --label "<label>" --pubkey pub.txt

Examples#

Dry-run (no upload)#

agentpm publish --dry-run

Sample output:

• Reading credentials…
✓ Reading credentials (0ms)
• Validating manifest…
✓ Validating manifest (3ms) — schema + semantics
• Packaging files…
✓ Packaging files (24ms) — 23866 bytes, sha256: fca0ef9660eb
Dry-run: artifact created at target/agentpm/summarize-0.1.3.tar.gz

Dry-run with strict (warnings become errors)#

agentpm publish --dry-run --strict

Sample output (fails on warning):

• Reading credentials…
✓ Reading credentials (0ms)
• Validating manifest…
  [WARN ] `description` should not be empty
        at instance /description
✗ Validating manifest (3ms) — failed
Error: Manifest validation failed (strict=true)

Actual publish#

agentpm publish

Sample output:

• Reading credentials…
✓ Reading credentials (0ms)
• Validating manifest…
✓ Validating manifest (2ms) — schema + semantics
• Packaging files…
✓ Packaging files (4ms) — 23866 bytes, sha256: fca0ef9660eb
• Uploading artifact…
✓ Uploading artifact (1.5s) — done
✓ Published summarize@0.1.3
  id:   21
  url:  https://www.agentpackagemanager.com/tools/db32af01-3c9f-47d7-ba91-06638f088531/v0.1.3/overview

What gets packaged#

Artifacts are written to: target/agentpm/<name>-<version>.tar.gz

The archive contains:

  • agent.json — your manifest (exactly as validated)
  • entrypoint — the executable/script declared in entrypoint.command (relative path preserved)
  • files — everything matched by files[] patterns (globs/dirs), with relative paths preserved

A SHA-256 digest is computed and shown in the output (also used for integrity verification on install).

Typical workflow#

  1. Finish your manifest (inputs/outputs, entrypoint, files, env vars, version).
  2. Run local checks:
agentpm lint --strict
agentpm publish --dry-run
  1. Commit changes (including updated version).
  2. Publish for real:
agentpm publish

Exit codes#

  • 0 — Published (or dry-run packaged) successfully.
  • 1 — Validation or upload failed (includes lint errors or strict warnings).

Troubleshooting#

  • Validation failed. Fix schema errors first (agentpm lint). If you used --strict, address warnings or omit --strict for non-blocking warnings.
  • Missing files in package. Ensure entrypoint.command points to a checked-in path, and add required assets/globs to files[].
  • Runtime/Interpreter mismatch. Lint will error if runtime.type doesn’t match entrypoint.command. Align them (e.g., python ↔ a Python entrypoint).

Notes & best practices#

  • Determinism. What you lint is what you publish. The packaged agent.json is the same one that passed validation.
  • Versioning. Bump versions semantically; publishing an existing version is rejected.
  • Reproducibility. Consumers will lock the artifact (checksum + version) in agent.lock, ensuring repeatable installs in CI and across teams.
←CLIinstall
→CLIwhoami