Skip to content

APS CLI Reference

The aps CLI is the reference implementation of the Agent Packaging Standard tooling.

It is responsible for:

  • Building APS agent packages
  • Running agents locally from a package
  • Publishing and pulling from registries
  • Inspecting manifests and metadata
  • Streaming logs and debugging runs

Installation

From a local clone of this repository:

# From repo root
cd cli

# Editable install for local development
pip install -e .
````

Once installed, verify:

```bash
aps --help
aps --version

CLI Overview

aps [GLOBAL OPTIONS] <command> [COMMAND OPTIONS]

Core commands (v0.1):

  • aps build – Package an agent into an APS artifact
  • aps run – Run an agent from a packaged or source directory
  • aps publish – Publish a package to a registry
  • aps pull – Pull a package from a registry into local cache
  • aps inspect – Show manifest, metadata, and capabilities
  • aps logs – View or stream logs for a run
  • aps lint – Validate an agent package / manifest (where implemented)

Run aps <command> --help for the exact options supported in your installed version.

Global Options

Common global flags (may evolve across versions):

  • -h, --help – Show help for the CLI or a specific command
  • --version – Show CLI version
  • --log-level {debug,info,warning,error} – Control verbosity
  • --registry <url> – Override default registry endpoint (for publish/pull/run)

Example:

aps --log-level debug --registry http://localhost:8080 publish dist/echo-agent.aps.tar.gz

aps build

Builds an APS-compliant package from an agent directory.

Synopsis:

aps build [OPTIONS] <AGENT_PATH>

Typical inputs:

  • AGENT_PATH – Path to the agent source directory containing:

  • aps.yaml or manifest.yaml (APS manifest)

  • Code entrypoint (e.g., agent.py)
  • Any supporting files

Common options:

  • -o, --output <path> – Output file path (e.g., dist/myagent.aps.tar.gz)
  • --no-cache – Do not reuse previous build layers (if applicable)

Example:

aps build examples/echo-agent -o dist/echo-agent.aps.tar.gz

aps run

Runs an agent from a local directory or built package.

Agents follow the APS runtime contract (stdin → stdout JSON).

Synopsis:

aps run [OPTIONS] <AGENT_PATH_OR_PACKAGE>

Common options:

  • --stream – Stream tokens/responses as they are produced
  • --registry <url> – If running a package that must be pulled first
  • --env KEY=VALUE – Inject runtime environment variables (if supported)

Examples:

Run directly from source:

aps run examples/echo-agent --stream

Run from a built package:

aps run dist/echo-agent.aps.tar.gz

Using stdin → stdout JSON contract:

echo '{"aps_version":"0.1","operation":"run","inputs":{"text":"hello"}}' \
  | aps run examples/echo-agent

aps publish

Publishes a built APS package to a registry.

Synopsis:

aps publish [OPTIONS] <PACKAGE_PATH>

Common options:

  • --registry <url> – Target registry URL (e.g., https://registry.aps.dev)
  • --auth-token <token> – Registry auth (if required)
  • --force – Overwrite existing version (if policy allows)

Example:

aps publish \
  --registry http://localhost:8080 \
  dist/echo-agent.aps.tar.gz

aps pull

Pulls an APS package from a registry into the local cache or filesystem.

Synopsis:

aps pull [OPTIONS] <AGENT_REF>

Where AGENT_REF may be something like:

  • echo-agent:0.1.0
  • myorg/rag-agent:latest

Common options:

  • --registry <url> – Registry URL
  • -o, --output <path> – Where to write the pulled package
  • --no-cache – Force re-download even if cached

Example:

aps pull echo-agent:0.1.0 --registry http://localhost:8080 -o dist/echo-agent.aps.tar.gz

aps inspect

Shows what’s inside a package or agent directory.

Synopsis:

aps inspect <AGENT_PATH_OR_PACKAGE>

What it can display (depending on implementation):

  • Manifest fields (name, version, publisher)
  • Capabilities and tools
  • Runtime entrypoint
  • Declared policies
  • Dependencies and environment

Example:

aps inspect dist/echo-agent.aps.tar.gz

aps logs

Displays logs for local runs (and eventually remote ones).

Synopsis:

aps logs [OPTIONS] <RUN_ID_OR_PATH>

Common options:

  • -f, --follow – Stream logs as they are produced
  • --tail <N> – Show the last N lines
  • --since <duration> – Filter logs by relative time (e.g., 5m, 1h)

Examples:

# Show logs for the most recent run of an agent
aps logs examples/echo-agent

# Follow logs for a given run ID (if your version exposes IDs)
aps logs --follow 2025-11-07T21-03-12Z-echo

aps lint

Validates a package or agent directory against the APS spec.

Synopsis:

aps lint <AGENT_PATH_OR_PACKAGE>

Checks may include:

  • Required manifest fields present
  • Version and ID formatting
  • Referenced files exist
  • Basic schema compliance

Example:

aps lint examples/echo-agent

Exit Codes

  • 0 – Success
  • 1 – General error (invalid input, runtime failure)
  • 2 – Validation / lint error
  • >=10 – Reserved for future, more specific error classes

See Also