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

安装和配置 Anysite CLI

## 安装

  
#### One-Line Installer

    最快的安装方式（macOS / Linux）。如果系统中尚未安装 [uv](https://docs.astral.sh/uv/)，会自动引导安装，
    因此无需预先安装 Python：
    ```bash
    curl -fsSL https://raw.githubusercontent.com/anysiteio/anysite-cli/main/install.sh | bash
    ```
    默认会安装所有扩展（数据集、LLM、PostgreSQL、ClickHouse），并提供交互式设置步骤来配置您的 API 密钥和 LLM
    提供商。可选参数：
    ```bash
    # Only dataset pipelines (DuckDB + PyArrow)
    curl -fsSL https://raw.githubusercontent.com/anysiteio/anysite-cli/main/install.sh | bash -s -- --extras data

    # Minimal install (no optional dependencies)
    curl -fsSL https://raw.githubusercontent.com/anysiteio/anysite-cli/main/install.sh | bash -s -- --extras none

    # Skip the interactive API key / LLM setup prompt
    curl -fsSL https://raw.githubusercontent.com/anysiteio/anysite-cli/main/install.sh | bash -s -- --no-setup

    # Install a specific version
    curl -fsSL https://raw.githubusercontent.com/anysiteio/anysite-cli/main/install.sh | bash -s -- --version 0.3.23

    # Upgrade an existing installation
    curl -fsSL https://raw.githubusercontent.com/anysiteio/anysite-cli/main/install.sh | bash -s -- --upgrade

    # Uninstall (config in ~/.anysite/ is kept)
    curl -fsSL https://raw.githubusercontent.com/anysiteio/anysite-cli/main/install.sh | bash -s -- --uninstall
    ```
    `--extras` 接受 `all`（默认）、`data`、`llm`、`db` 或 `none`。
  
  
#### Homebrew

    ```bash
    brew tap anysiteio/cli https://github.com/anysiteio/anysite-cli
    brew install anysite
    ```
  
  
#### pip

    ```bash
    pip install anysite-cli
    ```
    
> 
      需要 **Python 3.11** 或更高版本。
    
  
  
#### From Source

    ```bash
    git clone https://github.com/anysiteio/anysite-cli.git
    cd anysite-cli
    python -m venv .venv
    source .venv/bin/activate
    pip install -e .
    ```
  

### 可选扩展

根据需要安装附加功能：

| 扩展包 | 命令 | 提供的功能 |
|---------|---------|--------------|
| **Data** | `pip install "anysite-cli[data]"` | 用于数据集管道和 SQL 查询的 DuckDB + PyArrow |
| **LLM** | `pip install "anysite-cli[llm]"` | 支持 OpenAI 和 Anthropic 模型的 LLM 分析 |
| **PostgreSQL** | `pip install "anysite-cli[postgres]"` | PostgreSQL 数据库适配器 |
| **ClickHouse** | `pip install "anysite-cli[clickhouse]"` | ClickHouse 数据库适配器 |
| **All** | `pip install "anysite-cli[all]"` | 以上所有可选依赖 |

> 
  `anysite-cli[mysql]` 和 `anysite-cli[db]` 也是可安装的 pip 扩展（会安装 MySQL 客户端库），但当前 CLI
  版本没有可用的 MySQL 数据库适配器 — 可正常使用的集合见
  [Database Connections](/docs/cli/database/connections?lang=zh)。

### 验证安装

```bash
anysite --version
```

## 身份验证

  
#### Browser login (recommended)

    ```bash
    anysite auth login
    ```
    打开浏览器进行 OAuth2 授权。批准后，CLI 会存储一个有效期为 30 天的访问令牌。可用以下命令检查状态或退出登录：
    ```bash
    anysite auth status
    anysite auth logout
    ```
  
  
#### API key

    从 [app.anysite.io](https://app.anysite.io/billing) 获取您的 API 密钥并进行设置：
    ```bash
    anysite config set api_key YOUR_API_KEY
    ```

    > ACTION FOR THE HUMAN: copy your API key at https://app.anysite.io/billing — an agent cannot obtain it.

    或通过环境变量设置：
    ```bash
    export ANYSITE_API_KEY=YOUR_API_KEY
    ```

    > ACTION FOR THE HUMAN: copy your API key at https://app.anysite.io/billing — an agent cannot obtain it.

  

密钥解析顺序：`--api-key` 标志，其次是 `ANYSITE_API_KEY`，然后是来自 `anysite auth login` 的 OAuth
令牌，最后是配置文件中的 `api_key`。

### Update Schema Cache

模式缓存支持端点发现（`anysite describe`）以及 `anysite api` 的自动参数类型转换：

```bash
anysite schema update
```

### 配置管理

配置存放在 `~/.anysite/config.yaml`（可通过 `ANYSITE_CONFIG_DIR` 覆盖目录）：

```bash
# View all settings
anysite config list

# Get a specific setting
anysite config get api_key

# Set a value (dotted keys nest under a YAML map, e.g. defaults.format)
anysite config set defaults.format table

# Show config file path
anysite config path

# Reset to defaults (asks for confirmation unless --force)
anysite config reset --force
```

### 配置优先级

配置按以下顺序解析（优先级从高到低）：

1. **CLI 标志** — 例如在运行的命令上加 `--format csv`
2. **环境变量** — `ANYSITE_API_KEY`、`ANYSITE_BASE_URL`、`ANYSITE_CONFIG_DIR`
3. **配置文件** — `~/.anysite/config.yaml`
4. **默认值** — 包括 `base_url`（`https://api.anysite.io`）和 `timeout`（300 秒）

> 
  CI/CD 环境建议使用环境变量，本地开发建议使用配置文件。

## Claude Code Skill

一键安装脚本会自动安装一个 Claude Code 技能（安装到 `~/.claude/skills/anysite-cli/`），因此执行
`curl ... | bash` 后 Claude Code 就已经具备命令参考和管道配置方面的知识。若要手动添加或更新它 —
例如在使用 pip/Homebrew 安装时 — 可使用 Claude Code 插件市场：

  
#### Add the skills marketplace

    ```bash
    /plugin marketplace add https://github.com/anysiteio/agent-skills
    ```
  
  
#### Install the skill

    ```bash
    /plugin install anysite-cli@anysite-skills
    ```
  

关于 AnySite 技能在 Claude Code 中的通用工作方式，见 [Agent Skills](/docs/agent-skills?lang=zh)。

## Global Options

以下选项可在顶层 `anysite` 命令上使用，位于任何子命令之前：

```bash
anysite [OPTIONS] COMMAND
```

| 选项 | 描述 |
|--------|-------------|
| `--api-key TEXT` | API 密钥（或设置 `ANYSITE_API_KEY`） |
| `--base-url TEXT` | API 基础 URL（或设置 `ANYSITE_BASE_URL`） |
| `--debug` | 启用调试输出 |
| `--no-color` | 禁用彩色输出 |
| `--human` | 强制使用人类可读输出（覆盖管道中的自动 JSON） |
| `--non-interactive` | 禁用交互式提示（当 stdin 不是 TTY 时自动启用） |
| `--version`, `-v` | 显示版本并退出 |
| `--help` | 显示帮助 |

> 
  `--json` 不是全局标志 — 它是在各个子命令上单独定义的（`describe --json`、`config list --json`、
  `db discover --json` 等）。`anysite api` 本身没有 `--json` 标志：请改用 `--format json`（默认值）。
  哪些命令返回结构化 JSON 信封、哪些返回原始格式化数据，见 [Agent Protocol](/docs/cli/agent-protocol?lang=zh)。

## 故障排查

  
#### Command not found: anysite

    确认安装目录在您的 `PATH` 中。一键安装脚本会自动将 `~/.local/bin` 添加到您的 shell 配置文件 —
    重启终端，或运行：
    ```bash
    export PATH="$HOME/.local/bin:$PATH"
    ```
    如果安装在虚拟环境中，请先激活它：
    ```bash
    source .venv/bin/activate
    ```
  
  
#### Python version error

    Anysite CLI 需要 Python 3.11 及以上版本。检查您的版本：
    ```bash
    python3 --version
    ```
    可以考虑使用 [pyenv](https://github.com/pyenv/pyenv) 管理多个 Python 版本，或使用一键安装脚本，
    它会通过 `uv` 自行引导安装 Python。
  
  
#### Schema update fails

    如果 `anysite schema update` 失败，请检查您的 API 密钥和网络连接：
    ```bash
    anysite auth status
    curl -s https://api.anysite.io/openapi.json | head -c 100
    ```
  
  
#### Permission denied on install

    使用虚拟环境或 `--user` 标志：
    ```bash
    python -m venv .venv && source .venv/bin/activate
    pip install anysite-cli
    ```
  

## 后续步骤

  
#### Make API Calls

    开始通过单次 API 请求提取数据，并发现可用端点
  
  
#### Agent Protocol

    结构化错误、退出码，以及从其他程序中调用本 CLI 的脚本方式