AgentPM™

lint#

Validate your agent.json (or a folder of manifests) against the AgentPM schema and common best practices.

Overview#

agentpm lint checks schema conformance and common pitfalls. It can print results in multiple formats, optionally treat warnings as errors, and (lightly) auto-fix a few safe issues.

Command synopsis#

agentpm lint [PATHS...] [--schema <URL|PATH>] [--strict] [--format <pretty|json|ndjson>] [--fix]

Arguments#

  • PATHS (default: ./agent.json). Files/dirs/globs to lint. Directories are scanned recursively for agent.json.
  • --schema <URL|PATH>. Override the default schema source. By default, the CLI uses ./schemas/agentpm.manifest.schema.json when it exists relative to the current working directory; otherwise it uses the bundled schema version shipped with the CLI.
  • --strict. Treat warnings as errors (schema violations are always errors).
  • --format <pretty|json|ndjson> (default: pretty). Choose human-readable output or machine-friendly JSON/NDJSON.
  • --fix. Attempt non-invasive automatic fixes (currently: inject $schema if missing).
Tip

Use --format=json or --format=ndjson in CI and parse the result for gating.

Examples#

Lint the current manifest#

agentpm lint

Sample output (missing description):

✗ agent.json
  [ERROR] "description" is a required property
        vs schema  /required
Error: Lint failed

Lint multiple paths (file + directory + glob)#

agentpm lint agent.json .agentpm/tools/**/agent.json

Use a custom schema#

agentpm lint --schema ./schemas/dev.agentpm.schema.json

You can also point --schema at a hosted URL explicitly if you need to validate against a remote schema source.

Strict mode (warnings become errors)#

agentpm lint --strict

Machine-readable output#

agentpm lint --format=json
[
  {
    "file": "agent.json",
    "ok": false,
    "issues": [
      {
        "file": "agent.json",
        "level": "error",
        "message": "\"description\" is a required property",
        "instance_path": "",
        "schema_path": "/required"
      }
    ]
  }
]
Error: Lint failed

Auto-fix safe issues#

agentpm lint --fix
# currently adds a $schema field if it's missing

How lint classifies issues#

Always errors (schema violations):

  • Any JSON Schema validation failure. (Example: "description" is a required property)

Warnings (unless --strict):

  • Missing $schema. Message: Missing $schema; editors may lack IntelliSense.
  • Empty description. Message: description should not be empty.

Semantic error checks (beyond schema):

  • Interpreter mismatch between runtime.type and entrypoint.command. Error message example: runtime.type should match entrypoint.command (python vs node).
  • Loop graph validation for kind: "loop" manifests (entry phase, transitions, reachable terminals, checkpoints, and error-policy consistency).
  • Agent binding membership validation for kind: "agent" manifests (bindings package identities must already be declared in the matching top-level dependency collection).
Why this matters

Lint catches issues early so installs and publishes are predictable. agentpm publish runs lint automatically and will block the publish on any lint errors.

Exit codes#

  • 0 — All checked manifests passed (no errors; warnings allowed unless --strict).
  • 1 — Lint failed (any error, or any warning when --strict is set).
  1. Run agentpm lint locally during development.
  2. Use agentpm lint --format=json in CI to gate merges.
  3. Add --strict for release branches to enforce clean manifests.
  4. Let --fix add $schema automatically; commit the change.

Loop and binding boundary#

For Loop and Agent binding manifests, agentpm lint intentionally stays local:

  • it validates Loop graph structure and determinism
  • it validates that Agent bindings reference already-declared top-level package identities
  • it does not resolve Loop phase IDs against an installed Loop package
  • it does not resolve Memory spaces or operations against installed Memory Blueprints
  • it does not compare Loop access intent with Agent bindings and reject conflicts

Notes & gotchas#

  • $schema field. Including $schema enables IDE IntelliSense and makes the schema version explicit. Lint will add it for you with --fix.
  • Globs & directories. When passing directories, ensure your shell doesn’t expand globs unexpectedly; quote them if needed (e.g., "tools/**/agent.json").
←CLIlogin
→CLIinstall