CLI reference

The asmp CLI talks to the registry on :7700. Installed by bootstrap to ~/.asmp/bin/asmp.

# Add to PATH once (optional)
export PATH="$HOME/.asmp/bin:$PATH"

asmp litmus

Install

Bootstrap installs the CLI alongside the registry server:

curl -fsSL https://raw.githubusercontent.com/agent-service-manifest-protocol/agentservicemanifest.io/main/scripts/bootstrap-asmp.sh | bash

Manual install:

mkdir -p ~/.asmp/bin
curl -fsSL https://raw.githubusercontent.com/agent-service-manifest-protocol/agentservicemanifest.io/main/scripts/asmp \
  -o ~/.asmp/bin/asmp
chmod +x ~/.asmp/bin/asmp

Requires Python 3.10+ and pyyaml for announce / register (bootstrap installs pyyaml).

Registry URL

The CLI resolves the registry in this order:

1. ASMP_REGISTRY_URL environment variable
2. registry.api in ~/.asmp/host.yaml
3. http://127.0.0.1:7700 (default)

ASMP_REGISTRY_URL=http://127.0.0.1:7700 asmp health

Exit codes

Code	Meaning
0	Success
1	Registry unreachable, lookup miss, or litmus failure
2	Usage error (missing subcommand, invalid flag)

Commands

asmp health

Registry summary — total services, healthy/unhealthy counts, sections.

asmp health
asmp health --json

asmp host

Print the host profile from GET /host.

asmp host

asmp list

List registered services. Grouped by section in human output.

asmp list
asmp list --section tools
asmp list --healthy
asmp list -q email
asmp list --json

Flag	Description
--section	Filter by section (tools, cli, daemons, …)
--healthy	Only services passing health check
-q, --query	Search name, description, or capability

asmp get <name>

One service with index metadata (source, sync, generation, status).

asmp get director-daemon
asmp get agentservicemanifest-io --json

asmp find

Find services by capability or keyword.

asmp find --capability email.ingest
asmp find -c asmp.marketing
asmp find --query director

Returns exit code 1 when no matches.

asmp caps

List all known capabilities, or filter by provider.

asmp caps
asmp caps --provides email.ingest

asmp scan

Walk discovery.scan_paths and sync shipped asmp.yaml files into ~/.asmp/services/.

asmp scan
asmp scan --json

Equivalent to POST /discover/scan. See Announce & discovery.

asmp reload

Re-read the index from disk without scanning sources.

asmp reload

asmp announce <manifest>

Handshake register from a shipped manifest file. Increments generation and sets sync: announce.

asmp announce ./asmp.yaml
asmp announce ~/repos/my-service/asmp.yaml --json

asmp register <manifest>

Direct register (POST /services) without handshake ack.

asmp register ~/.asmp/services/hello.asmp.yaml

asmp todo <name>

Drop a discovery breadcrumb when you find a real agent, service, or CLI that ASMP cannot look up yet. Append-only — does not register the service.

asmp todo my-daemon \
  --note "Runs on :8080, handles PDF parsing" \
  --repo ~/repos-personal/my-daemon \
  --hint "Add asmp.yaml and run asmp announce" \
  --found-by cursor-agent

Writes to ~/.asmp/discoveries.jsonl via POST /discoveries.

asmp todos

List discovery notes for services seen but not yet registered (de-duped against the index).

asmp todos
asmp todos --json

When asmp get or asmp find misses, the CLI prints the same asmp todo hint so gaps self-heal across sessions.

asmp litmus

Six gate checks — health, host, services, capabilities, email.ingest lookup, and discover scan.

asmp litmus

Pass when all six checks succeed. Use after bootstrap or registry upgrades.

Common workflows

Verify bootstrap worked

asmp litmus

Find who handles email

asmp find --capability email.ingest

Pick up a new repo with asmp.yaml

asmp scan
asmp get my-new-service

Announce on service start

asmp announce /path/to/my-service/asmp.yaml

Self-heal a discovery gap

You looked for a capability or service name and got nothing — but you know it exists:

asmp todo mystery-daemon --note "systemd unit on :9090" --repo ~/repos-aic/mystery
asmp todos
# later: author asmp.yaml, then asmp announce ./asmp.yaml

CLI vs MCP vs curl

Task	CLI	MCP	HTTP
List services	asmp list	service_list()	GET /services
Find by capability	asmp find -c X	service_find(capability=X)	GET /capabilities?provides=X
Scan sources	asmp scan	service_scan()	POST /discover/scan
Drop discovery todo	asmp todo <name>	service_todo(name=…)	POST /discoveries
List discovery todos	asmp todos	service_todos()	GET /discoveries
Gate checks	asmp litmus	—	manual curls

Agents in IDE sessions should use MCP. Humans and scripts use the CLI. Automation can use either CLI or curl.

Next

Discover services

Agent-facing discovery patterns

Registration API

Full HTTP reference