> ## Agent Instructions
>
> Base URL: https://api.anysite.io
> Authentication: send the `access-token` header. Do NOT use `Authorization: Bearer`.
> Full endpoint catalog: https://app.anysite.io/docs
# 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:
- A **JSON envelope** with `ok`, `result`/`error`, `hints`, and `meta`
- **Exit codes** for programmatic flow control
- **Error codes** with `retryable` flag and `suggestions`
- **Next-step hints** so agents discover follow-up commands without documentation

## 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 |

```bash
# 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

```json
{
  "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

```json
{
  "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 |

```bash
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:

```bash
# 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:

```bash
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:

```bash
# 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

```bash
# 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

```bash
#!/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:

```bash
# 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