Agent Protocol

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

Overview

Anysite CLI is agent-native — it auto-detects when stdout is a pipe or subprocess (non-TTY) and switches all output to structured JSON. No flags, no configuration. AI agents like Claude Code, n8n, Make, and custom scripts get machine-readable responses out of the box.

Every command returns:

Auto-Detection

Context Default Output Override
Terminal (TTY) Human-readable Rich text --json to force JSON
Pipe / subprocess (no TTY) Structured JSON envelope --human to force human text 
# In terminal — human-readable output (default)
anysite api /api/linkedin/user user=satyanadella

# In terminal — force JSON output
anysite api /api/linkedin/user user=satyanadella --json

# In pipe — JSON automatically
anysite api /api/linkedin/user user=satyanadella | jq '.result.name'

# In pipe — force human output
anysite api /api/linkedin/user user=satyanadella --human | less

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

JSON Envelope

Success Response

{
  "ok": true,
  "result": {
    "name": "Satya Nadella",
    "headline": "Chairman and CEO at Microsoft",
    "follower_count": 12500000
  },
  "hints": [
    {
      "action": "Get posts",
      "command": "anysite api /api/linkedin/user/posts user=satyanadella"
    },
    {
      "action": "Save to database",
      "command": "anysite db insert mydb --table profiles --stdin"
    }
  ],
  "meta": {
    "version": "0.3.0",
    "command": "anysite api /api/linkedin/user"
  }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "Authentication failed: invalid or expired API key",
    "retryable": false,
    "suggestions": [
      "Set API key: anysite config set api_key <key>",
      "Or set environment variable: export ANYSITE_API_KEY=<key>"
    ]
  },
  "meta": {
    "version": "0.3.0",
    "command": "anysite api /api/linkedin/user"
  }
}

Always check the ok field first. Use error.code for programmatic handling, error.retryable to decide whether to retry, and error.suggestions for recovery 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 |
| `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 |
| `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 |

Hints

Every command returns next-step hints — suggested follow-up commands based on what you just did. In JSON mode, hints appear in the hints array. In human mode, they are printed as dim text on stderr.

Agents use hints to discover follow-up actions without consulting documentation:

# Collect hints from response
HINTS=$(anysite api /api/linkedin/user user=satyanadella | jq -r '.hints[].command')
echo "$HINTS"
# anysite api /api/linkedin/user/posts user=satyanadella
# anysite db insert mydb --table profiles --stdin

Discovery Payload

Run anysite with no arguments in a pipe to get a full discovery payload describing all CLI capabilities:

anysite | jq '.result'

The discovery payload includes:

Field Description
commands All available commands with descriptions and subcommands
agent_protocol How auto-JSON, --json, --human, --non-interactive work
output_schema Success and error envelope formats
exit_codes Machine-readable exit code meanings
installed_extras Which optional packages are available (data, llm, postgres, clickhouse)

This allows an agent to introspect the CLI on first run and plan its workflow without any prior knowledge.

Built-in Guide

The CLI includes a comprehensive dataset configuration guide accessible via the command line:

# 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

Agents can use anysite dataset guide --json to get a structured reference of all dataset pipeline features, source types, and configuration options.

Integration Examples

Pipe to jq

# Extract a specific field
anysite api /api/linkedin/user user=satyanadella | jq '.result.follower_count'

# Process batch results
anysite api /api/linkedin/search/users keywords="CTO" count=10 --json | \
  jq -r '.result[] | [.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 '.result'
elif [ $EXIT_CODE -eq 3 ]; then
  echo "Authentication failed. Check your API key."
  exit 1
elif [ $EXIT_CODE -eq 5 ]; then
  echo "Network error. Retrying in 5 seconds..."
  sleep 5
  anysite api /api/linkedin/user user="$1"
else
  ERROR=$(echo "$RESPONSE" | jq -r '.error.message')
  echo "Error: $ERROR"
  exit $EXIT_CODE
fi

Agent Workflow

A typical AI agent workflow with the CLI:

# 1. Discover CLI capabilities
anysite | jq '.result.commands'

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

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

# 4. Execute and parse
RESULT=$(anysite api /api/linkedin/user user=satyanadella)
echo "$RESULT" | jq '.ok'     # true
echo "$RESULT" | jq '.hints'  # next steps

Next Steps

Data Agent

AI agent for automated data collection using the agent protocol

Installation

Install the CLI and configure global options