Agent Protocol

Structured JSON output, exit codes, error codes, and two-level discovery for AI agent integration

Overview

Anysite CLI auto-detects when stdout is a pipe or subprocess (non-TTY) and switches most commands to structured JSON. No flags or configuration needed for scripts and AI agents.

Context	Default Output	Override
Terminal (TTY)	Human-readable Rich text	--json on the command, to force JSON
Pipe / subprocess (no TTY)	JSON	--human global flag, to force human text

# In terminal — human-readable output (default)
anysite config list

# In terminal — force JSON output
anysite config list --json

# In pipe — JSON automatically
anysite config list | jq '.result'

# In pipe — force human output
anysite config list --human | less

--non-interactive disables interactive prompts (confirmations, selections). It is auto-enabled whenever stdin is not a TTY.

--json is defined per-command, not globally — see Installation. Run anysite <command> --help to check whether a given command has a --json flag.

JSON Envelope

Most subcommands under config, db, dataset, llm, auth status, schema update, and changelog wrap their JSON output in an envelope:

Success:

{
  "ok": true,
  "result": { "...": "command-specific data" },
  "hints": [{"action": "Next step", "command": "anysite ..."}],
  "meta": {"version": "0.3.23", "command": "anysite db add"}
}

Error:

{
  "ok": false,
  "error": {
    "code": "CONNECTION_NOT_FOUND",
    "message": "Connection 'mydb' not found",
    "retryable": false,
    "suggestions": ["Add one with: anysite db add <name> --type sqlite --path ./data.db"]
  },
  "meta": {"version": "0.3.23"}
}

Example: adding a database connection returns the envelope, with hints for follow-up commands:

anysite db add local --type sqlite --path ./data.db --json | jq '.hints'

anysite api and anysite describe (list and single-endpoint modes) are the two exceptions: they print the API/schema data directly in the chosen --format, not the {ok, result, ...} envelope, and anysite api has no --json flag at all. Only anysite describe --search uses the envelope. Check ok only on commands documented above as envelope commands.

Where the envelope applies: check ok for success/failure, error.code for programmatic handling, error.retryable to decide whether to retry, and error.suggestions / hints for next steps.

Exit Codes

Code	Meaning	When
0	Success	Command completed successfully
1	General error	Unhandled error, server error
2	Usage error	Invalid arguments, missing required parameters
3	Authentication failed	Invalid or expired API key
4	Resource not found	Endpoint, connection, or source not found
5	Network error	Connection failure, timeout, rate limit

anysite api /api/linkedin/user user=satyanadella
case $? in
  0) echo "Success" ;;
  3) echo "Check your API key" ;;
  5) echo "Network issue, retrying..." ;;
  *) echo "Error: exit code $?" ;;
esac

Error Codes

API Errors

| Error Code | Exit Code | Retryable | Trigger |
|------------|-----------|-----------|---------|
| `AUTH_FAILED` | 3 | No | Invalid or expired API key |
| `RATE_LIMIT` | 5 | Yes | Too many requests |
| `NOT_FOUND` | 4 | No | Resource not found |
| `VALIDATION_ERROR` | 2 | No | Bad input parameters |
| `SERVER_ERROR` | 1 | Yes | API server error (5xx) |
| `NETWORK_ERROR` | 5 | Yes | Connection failure |
| `TIMEOUT` | 5 | Yes | Request timeout |

Database Errors

| Error Code | Exit Code | Retryable | Trigger |
|------------|-----------|-----------|---------|
| `CONNECTION_NOT_FOUND` | 4 | No | Database connection not configured |

Dataset Errors

| Error Code | Exit Code | Retryable | Trigger |
|------------|-----------|-----------|---------|
| `DATASET_ERROR` | 1 | No | Dataset operation failed |
| `CIRCULAR_DEPENDENCY` | 1 | No | Sources reference each other in a cycle |
| `SOURCE_NOT_FOUND` | 4 | No | Source not found in dataset config |

LLM Errors

| Error Code | Exit Code | Retryable | Trigger |
|------------|-----------|-----------|---------|
| `CONFIG_ERROR` | 2 | No | LLM provider not configured |
| `LLM_PROVIDER_ERROR` | 1 | Yes | LLM provider failure |
| `PROMPT_ERROR` | 1 | No | Prompt template error |

Two-Level Discovery

The CLI exposes a self-describing discovery payload in two levels, designed so an agent can plan a workflow without any prior knowledge of the tool.

Level 1: overview

Run anysite with no arguments in a pipe to get a compact discovery payload:

anysite | jq '.result'

result includes:

Field	Description
status	Current auth method, LLM provider, saved DB connections, schema/graph cache state
agent_protocol	How auto-JSON, --json, --human, --non-interactive work
output_schema	Success and error envelope shapes
exit_codes	Machine-readable exit code meanings
whats_new	Summary of the latest release
commands	Every top-level command with a description and, for command groups, one-line subcommand descriptions plus a detail_command hint
installed_extras	Which optional packages are available: data, llm, postgres, clickhouse, mysql

Level 2: per-group detail

For any command group, pipe empty input through it to get full options, curated examples, and tips:

echo '' | anysite db
echo '' | anysite dataset
echo '' | anysite llm

This returns each subcommand's options (factoring out ones common across the group), plus curated example invocations and tips — for example db's tips include piping API output straight into db insert.

Top-level commands without subcommands (api, describe) use the same mechanism when called with no arguments in a pipe:

echo '' | anysite api
echo '' | anysite describe

Hints

Commands that return the JSON envelope also return next-step hints — suggested follow-up commands. In JSON mode they appear in the hints array; in human mode they print as dim text on stderr.

anysite db add local --type sqlite --path ./data.db --json | jq -r '.hints[].command'

Built-in Guide

The dataset subsystem includes a comprehensive configuration reference:

# Full configuration reference
anysite dataset guide

# Specific section
anysite dataset guide --section sources

# Complete example config
anysite dataset guide --example advanced

# List all available sections and examples
anysite dataset guide --list

# JSON output for agents
anysite dataset guide --json

Integration Examples

Pipe to jq

anysite api /api/linkedin/user user=satyanadella | jq '.follower_count'

anysite api /api/linkedin/search/users keywords="CTO" count=10 --format jsonl | \
  jq -r '[.name, .headline] | @csv'

Shell Script with Error Handling

#!/bin/bash
RESPONSE=$(anysite api /api/linkedin/user user="$1" 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "$RESPONSE" | jq '.'
elif [ $EXIT_CODE -eq 3 ]; then
  echo "Authentication failed. Check your API key."
  exit 1
elif [ $EXIT_CODE -eq 5 ]; then
  echo "Network error."
else
  echo "Error: exit code $EXIT_CODE"
  exit $EXIT_CODE
fi

Agent Workflow

# 1. Discover CLI capabilities and current status
anysite | jq '.result.status'

# 2. Discover available API endpoints
anysite describe --search "linkedin" --json

# 3. Inspect a specific endpoint
anysite describe /api/linkedin/user --json

# 4. Execute and check the exit code
anysite api /api/linkedin/user user=satyanadella
echo "exit: $?"

Next Steps

Dataset Pipelines

Declarative multi-source collection built on the same protocol

Installation

Install the CLI and configure global options