Agent Integration

spectra-tools CLIs are designed from the ground up for AI agent consumption. Every CLI includes built-in discovery, schema introspection, structured output, and one-command registration — making them first-class tools in any agent workflow.

Why this matters

Most CLIs are built for humans and retrofitted for machines. spectra-tools takes the opposite approach: every command is agent-ready by default, with human-friendly output as the default view.

• Structured output — --format json on any command, every time
• Self-describing — agents can discover capabilities without documentation
• Schema-first — JSON Schema for every command's inputs and outputs
• Zero-config registration — skills add and mcp add just work

Discover capabilities

CLI manifest (--llms / --llms-full)

Every CLI can export its command surface for agent discovery:

• --llms — compact command index (names, one-line descriptions)
• --llms-full — full manifest with arguments, environment variables, output fields, and examples

# Compact index — quick discovery
assembly-cli --llms
etherscan-cli --llms

# Full manifest — complete reference
assembly-cli --llms-full
etherscan-cli --llms-full
xapi-cli --llms-full
erc8004-cli --llms-full

Use --llms for fast discovery and --llms-full when agents need the complete command reference.

Command schema (--schema)

Get the JSON Schema for any specific command:

assembly-cli governance proposals --schema
etherscan-cli account balance --schema
xapi-cli posts search --schema

Use schemas to validate inputs before execution or to generate type-safe wrappers.

Register with your agent

As a local skill

assembly-cli skills add
etherscan-cli skills add
xapi-cli skills add
erc8004-cli skills add

This writes skill metadata to your local agent's skill discovery path. Agents that support skill directories (like OpenClaw) will automatically discover the CLI.

As an MCP server

assembly-cli mcp add
etherscan-cli mcp add
xapi-cli mcp add
erc8004-cli mcp add

This registers the CLI as a Model Context Protocol server, making it available to any MCP-compatible agent or IDE.

Structured output

Data profile (default for scripts)

Use --format json (or --json) for clean, parseable output:

assembly-cli governance proposals --limit 3 --json

[
  { "id": "1", "title": "Proposal Alpha", "status": "active" },
  { "id": "2", "title": "Proposal Beta", "status": "passed" }
]

On success, you get the data directly. On error, you get an error object. No wrapper, no envelope — just the payload.

Envelope profile (for orchestration)

Add --verbose for a full metadata envelope:

assembly-cli governance proposals --limit 3 --json --verbose

{
  "ok": true,
  "data": [...],
  "meta": {
    "command": "governance proposals",
    "duration": "142ms"
  }
}

The envelope includes execution metadata useful for logging, telemetry, and orchestration pipelines.

Other formats

--format yaml    # readable key-value output
--format md      # markdown tables and headings
--format jsonl   # newline-delimited JSON for streaming

Control output size

For LLM context management, use token-aware pagination:

assembly-cli governance proposals --json --token-limit 2000
assembly-cli governance proposals --json --token-limit 2000 --token-offset 2000

Or filter to specific fields:

etherscan-cli account balance 0x... --json --filter-output "balance,symbol"

Recommended agent pipeline

1. Discover    →  assembly-cli --llms (or --llms-full for details)
2. Introspect  →  assembly-cli governance proposals --schema
3. Execute     →  assembly-cli governance proposals --limit 5 --json
4. Validate    →  check exit code + parse JSON
5. Route       →  feed results into agent memory/prompt

This pattern works with any orchestrator — LangChain, OpenClaw, custom agents, or simple shell scripts.

Observability & trace correlation

When OpenTelemetry is enabled, every CLI invocation produces distributed traces that can be correlated across agent workflow steps.

Trace structure

Each CLI command creates a root span (cli.command.<name>) that contains:

• HTTP child spans — one per API request, with method, URL, status code, and timing
• Error events — recorded with stack traces when commands or requests fail
• Sanitized attributes — command arguments appear as span attributes with sensitive values stripped

Agent workflow correlation

To correlate traces across multiple CLI invocations in an agent pipeline, set OTEL_SERVICE_NAME to a consistent value and use trace context propagation:

# All CLIs report under the same service
export OTEL_SERVICE_NAME="my-agent-pipeline"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

# Step 1: Discover governance proposals
assembly-cli governance proposals --limit 5 --json

# Step 2: Look up voter details
etherscan-cli account balance 0x... --json

# Step 3: Post analysis
xapi-cli posts create --text "Governance update: ..."

Each step produces spans under the same service name, making it easy to trace the full workflow in your collector UI (Jaeger, Grafana, etc.).

Zero overhead when disabled

When OTEL_EXPORTER_OTLP_ENDPOINT is not set and SPECTRA_OTEL_ENABLED is not true, the telemetry module:

• Does not import any OTEL SDK modules (lazy-loading)
• Creates no spans, no metrics, no exporters
• Adds less than 1ms overhead per command invocation

This makes it safe to leave the instrumentation code in place for production CLIs without impacting performance.

Example: agent skill file

After running assembly-cli skills add, your agent gets a skill definition like:

name: assembly-cli
description: Assembly governance CLI for Abstract
commands:
  - governance proposals
  - governance proposal
  - members list
  - council seats
  - treasury balances
  - forum threads
  # ... full command list

The agent can then reason about which command to call based on user intent, execute it with --json, and parse the structured response.