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

```bash
# 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](/docs/cli/installation#global-options).
  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:**
```json
{
  "ok": true,
  "result": { "...": "command-specific data" },
  "hints": [{"action": "Next step", "command": "anysite ..."}],
  "meta": {"version": "0.3.23", "command": "anysite db add"}
}
```

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

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

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

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

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

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

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

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

## Integration Examples

### Pipe to jq

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

```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 '.'
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

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