acpctl 0.1.1

Command line interface for the Agent Communication Protocol (ACP)

ACP CLI (acpctl)

The ACP CLI provides a simple command-line interface for interacting with the Agent Communication Protocol.

It allows developers and operators to:

• create and manage agent identities
• send and inspect messages
• test agent communication
• explore ACP-based systems

What is ACP?

ACP (Agent Communication Protocol) is a protocol for secure, identity-based communication between autonomous systems.

The CLI is the easiest way to experiment with ACP without writing code.

This project is not related to other packages using the acronym "ACP"

Current Functionality

Current phase includes:

• acp identity create
• acp identity show
• acp identity export
• acp identity verify
• acp discover get
• acp discover list
• acp discover well-known
• acp register put
• acp register update
• acp register show
• acp message send
• acp message capabilities
• acp agent run
• acp agent status
• acp transport list
• acp transport probe
• acp relay status
• acp relay health
• acp relay registry list
• acp relay registry show
• acp relay routes show
• acp relay ops stats
• acp relay ops failures
• acp config show
• acp config validate

Installation

From repository root:

pip install -e acp-runtime
pip install -e acpctl

Then run:

acp --help

From PyPI:

pip install acp-runtime acpctl

Config

CLI reads optional JSON config from:

• --config <path>
• or ACP_CONFIG_FILE
• or ~/.acp/config.json if it exists

Supported config keys:

{
  "storage_dir": ".acp-data",
  "discovery_scheme": "https",
  "relay_hints": ["https://relay.example"],
  "enterprise_directory_hints": [],
  "timeout_seconds": 5,
  "allow_insecure_http": false,
  "allow_insecure_tls": false,
  "ca_file": null,
  "mtls_enabled": false,
  "cert_file": null,
  "key_file": null,
  "key_provider": "local",
  "vault_url": null,
  "vault_path": null,
  "vault_token_env": "VAULT_TOKEN"
}

Global transport hardening flags:

• --allow-insecure-http local/dev/demo exception for http://
• --allow-insecure-tls disable TLS certificate verification
• --ca-file <path> custom CA bundle for HTTPS verification
• --mtls-enabled enable optional enterprise HTTP mTLS profile
• --cert-file <path> client/server certificate for mTLS profile
• --key-file <path> client/server private key for mTLS profile
• --key-provider <local|vault> select key custody backend
• --vault-url <url> Vault base URL when provider is vault
• --vault-path <path> Vault secret path prefix (or {agent_id} template)
• --vault-token-env <name> env var containing the Vault token

When key_provider=vault and mtls_enabled=true, cert_file/key_file may be supplied by provider material (leave both unset) or overridden explicitly (set both).

You can override storage directly:

acp --storage-dir /tmp/acp-data identity show --agent-id agent:demo@localhost:8088

Examples

Create identity:

acp identity create --agent-id agent:john.chess@demo

Create identity with endpoint and relay hint:

acp identity create \
  --agent-id agent:john.chess@demo \
  --direct-endpoint https://john.example.net/api/v1/acp/messages \
  --relay-hint https://relay.example.net

Show identity:

acp identity show --agent-id agent:john.chess@demo

Export identity document:

acp identity export --agent-id agent:john.chess@demo --out ./john.identity.json

Verify identity document:

acp identity verify --file ./john.identity.json

Discover identity:

acp discover get --agent-id agent:ricardo.chess@demo

Discover agent metadata from /.well-known/acp:

acp discover well-known https://ricardo.example.net --agent-id agent:ricardo.chess@demo

Overlay adoption bootstrap check (well-known first):

acp discover well-known https://overlay-service.example.net

List discovery cache:

acp discover list

Register local identity with relay:

acp register put \
  --agent-id agent:john.chess@demo \
  --relay https://relay.example.net \
  --endpoint https://john.example.net/api/v1/acp/messages

Update registration to publish MQTT hint:

acp register update \
  --agent-id agent:john.chess@demo \
  --relay https://relay.example.net \
  --transport mqtt \
  --broker mqtt://localhost:1883 \
  --topic acp/agent/john.chess.demo \
  --qos 1

Show relay registration:

acp register show --agent-id agent:john.chess@demo --relay https://relay.example.net

Send message payload:

acp message send \
  --from agent:john.chess@demo \
  --to agent:ricardo.chess@demo \
  --payload-json '{"kind":"ping","value":1}' \
  --delivery-mode auto

Request capabilities:

acp message capabilities \
  --from agent:john.chess@demo \
  --to agent:ricardo.chess@demo

Run a local agent runtime:

acp agent run \
  --agent-id agent:john.chess@localhost:8088 \
  --transport direct \
  --transport amqp \
  --port 8088

Check agent status:

acp agent status \
  --agent-id agent:john.chess@localhost:8088 \
  --relay https://relay.example.net

List transport configuration:

acp transport list --agent-id agent:john.chess@localhost:8088

Probe transport reachability:

acp transport probe --agent-id agent:john.chess@localhost:8088

Relay status:

acp relay status --relay https://relay.example.net

Relay health:

acp relay health --relay https://relay.example.net

Relay registry list/show:

acp relay registry list --relay https://relay.example.net --limit 50
acp relay registry show --relay https://relay.example.net --agent-id agent:john.chess@localhost:8088

Relay routes and ops:

acp relay routes show --relay https://relay.example.net --limit 50
acp relay ops stats --relay https://relay.example.net
acp relay ops failures --relay https://relay.example.net --limit 50

JSON output:

acp --json discover get --agent-id agent:ricardo.chess@demo

Local demo-only HTTP example (explicit override):

acp --allow-insecure-http relay status --relay http://localhost:8080

Optional HTTPS + mTLS example:

acp \
  --config ~/.acp/config.json \
  --mtls-enabled \
  --ca-file ./tls/ca.pem \
  --cert-file ./tls/client-cert.pem \
  --key-file ./tls/client-key.pem \
  transport probe --agent-id agent:john.chess@demo

Optional Vault-backed key-provider selection:

export VAULT_TOKEN="..."
acp \
  --key-provider vault \
  --vault-url https://vault.example.net \
  --vault-path secret/data/acp/identities \
  --json config show

Config validation:

acp config show
acp config validate

Security Notes

• Private keys are never printed by default.
• Identity verification uses existing SDK identity verification logic.
• Discovery uses existing SDK discovery order (cache, .well-known, relay/directory hints).
• No insecure identity bypass is added in this phase.
• acp message capabilities reports non-error no-response outcomes explicitly.
• HTTPS is the default for HTTP-based ACP paths.
• Local/dev/demo http:// use requires explicit --allow-insecure-http.
• HTTP mTLS is optional and enterprise-focused; ACP core protocol semantics are unchanged.
• For local/self-signed mTLS testing, set ca_file to your local CA bundle and keep allow_insecure_tls=false by default.