### Quick Start CC-Connect Setup

Source: https://github.com/cubenlp/chattool/blob/master/docs/tools/cc/index.md

Install Node.js, npm, and cc-connect, then initialize and start the service.

```bash
chattool setup cc-connect
chattool cc init -i --quiet
chattool cc start
```

--------------------------------

### Setup FRP Client (Local)

Source: https://github.com/cubenlp/chattool/blob/master/skills/frp-configurator/SKILL.md

Installs and configures the FRP client (`frpc`) on the local machine. Use the non-interactive mode with environment variables for automated setups.

```bash
bash scripts/setup_client.sh
```

```bash
# Non-interactive / Automated setup (Recommended for scripts)
# This avoids the "Connection Refused" error by setting the correct server upfront.
export FRP_SERVER_IP="x.x.x.x"     # Replace with your Server IP
export FRP_SERVER_PORT="7000"      # Replace with your Server Port
export FRP_AUTH_TOKEN="my-secret-token" # Replace with your Token
bash scripts/setup_client.sh -y    # Use -y to skip prompts
```

--------------------------------

### Setup Lark CLI with ChatTool

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/feishu-cli-doc-practice.md

Run `chattool setup lark-cli` to install the official `@larksuite/cli` package and configure it to reuse existing Feishu configurations managed by ChatTool. This simplifies the migration process.

```bash
chattool setup lark-cli
```

--------------------------------

### Install Node.js Interactively

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/codex.md

Allows interactive selection of Node.js versions to install. It checks for existing Node.js and npm installations and prompts for setup if dependencies are not met.

```bash
chattool setup nodejs -i
```

--------------------------------

### Install Node.js with ChatTool

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/codex.md

Installs the latest LTS version of Node.js using the chattool setup command. It also handles nvm initialization for detected shell rc files.

```bash
chattool setup nodejs
```

--------------------------------

### Setup Codex with Interactive API Key Input

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/codex.md

Initiates the Codex setup process, prompting the user to interactively enter their API key. It checks for Node.js >= 20 and npm, offering to install them if missing.

```bash
chattool setup codex
```

--------------------------------

### Setup FRP Server (Remote)

Source: https://github.com/cubenlp/chattool/blob/master/skills/frp-configurator/SKILL.md

Installs and configures the FRP server (`frps`) on the remote machine. Supports interactive setup.

```bash
bash scripts/setup_server.sh
```

--------------------------------

### GitHub Copilot Instructions Example

Source: https://github.com/cubenlp/chattool/blob/master/docs/development-guide/skills-platform-compat.md

Example of copilot-instructions.md for GitHub Copilot, outlining development practices.

```markdown
# Copilot Instructions

- 优先复用已有工具，避免引入新依赖
- 行为变更应同步补对应的 `cli-tests/*.md`
- PR 保持聚焦，改动范围最小化
```

--------------------------------

### Setup and Authentication for Lark CLI

Source: https://github.com/cubenlp/chattool/blob/master/skills/feishu/SKILL.md

Commands to set up and manage authentication for the Lark CLI. Use `--recommend` for guided login and `--no-wait` for non-blocking device flow.

```bash
chattool setup lark-cli
lark-cli auth status
lark-cli auth login --recommend
```

```bash
lark-cli auth login --recommend --no-wait
lark-cli auth login --device-code <DEVICE_CODE>
```

--------------------------------

### OpenCode Configuration with Debug Logging

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/opencode.md

Runs the OpenCode setup with debug logging enabled to view detailed installation and configuration steps.

```bash
chattool setup opencode --log-level DEBUG
```

--------------------------------

### Start a server and attach to it

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/opencode-cli-guide.md

Launches a local OpenCode server on a specified port and then connects to it.

```bash
opencode serve --port 4096
```

```bash
opencode attach http://localhost:4096
```

--------------------------------

### Initialize ChatTool Configuration Interactively

Source: https://github.com/cubenlp/chattool/blob/master/docs/configuration.md

Use `chatenv init -i` for an interactive setup that guides you through setting up API keys and parameters, saving them to type-specific env files.

```bash
chatenv init -i
```

```bash
chatenv init -i -t "OpenAI"
```

--------------------------------

### Gemini CLI Instructions Example

Source: https://github.com/cubenlp/chattool/blob/master/docs/development-guide/skills-platform-compat.md

Example of GEMINI.md for Gemini CLI, outlining project background and commands.

```markdown
# GEMINI.md

## 项目背景
这是一个 Python CLI 工具集。

## 指令
- 修改模块后运行对应测试
- 保持向后兼容，除非明确要求破坏性变更
```

--------------------------------

### Start MCP Service with ChatTool

Source: https://github.com/cubenlp/chattool/blob/master/README.md

Launch the standard MCP Server for use with Claude/Cursor by running `chattool mcp start`.

```bash
chattool mcp start
```

--------------------------------

### Set Up Development Environments with ChatTool

Source: https://github.com/cubenlp/chattool/blob/master/README.md

Configure Zsh and install/verify common Agent CLIs, WebUIs, and Docker environments using `chattool setup`. Specific environments like `zsh/codex/claude/opencode/hermes/lark-cli/docker` can be targeted. Use `--install-only` for pure installation/upgrades. `setup opencode` supports `--plugin auto-loop`.

```bash
chattool setup zsh/codex/claude/opencode/hermes/lark-cli/docker
```

```bash
setup hermes
```

```bash
setup opencode/codex/claude/hermes --install-only
```

```bash
setup opencode --plugin auto-loop
```

--------------------------------

### Basic Lark Bot Setup

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/larkbot_v053.md

A minimal example demonstrating how to set up a Lark Bot to receive and reply to text messages. Requires importing LarkBot and defining a message handler.

```python
from chattool.tools.lark import LarkBot

bot = LarkBot()

@bot.on_message
def handle(ctx):
    ctx.reply(f"收到：{ctx.text}")

bot.start()
```

--------------------------------

### Setup Lark CLI

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Installs the official 'lark-cli' and reuses ChatTool's Feishu configuration. Supports detailed logs and reusing 'chatenv' Feishu profiles.

```bash
chattool setup lark-cli
```

```bash
chattool setup lark-cli --log-level DEBUG
```

```bash
chattool setup lark-cli -e work
```

```bash
chattool setup lark-cli -e ~/.chatarch/envs/Feishu/work.env
```

--------------------------------

### Start OpenCode web interface

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/opencode-cli-guide.md

Launches the OpenCode service and opens its web-based user interface in the browser.

```bash
opencode web
```

--------------------------------

### Chattool Zsh Setup Missing Zsh

Source: https://github.com/cubenlp/chattool/blob/master/tests/mock-cli-tests/setup/test_chattool_setup_zsh_basic.md

Tests the scenario where Zsh is missing. The command should fail gracefully and provide instructions to install Zsh using apt.

```sh
mock which git exists and zsh missing
run chattool setup zsh --no-omz --no-aliases -I
assert exit code is non-zero
assert output includes sudo apt install zsh -y
```

--------------------------------

### Dry Run Workspace Setup

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Simulates the workspace setup process without making any changes to the file system. Useful for previewing the generated structure.

```bash
chattool setup workspace ~/workspace/demo --dry-run -I
```

--------------------------------

### Start a headless server

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/opencode-cli-guide.md

Launches OpenCode as a background service without a user interface.

```bash
opencode serve
```

--------------------------------

### Configure and Start CC-Connect

Source: https://github.com/cubenlp/chattool/blob/master/README.md

Quickly configure and launch CC-Connect using the `chattool cc` command.

```bash
chattool cc
```

--------------------------------

### Setup Hermes Agent

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Installs or checks the Hermes Agent and configures basic OpenAI-compatible parameters. This command encapsulates the official Hermes install.sh script.

```bash
chattool setup hermes
```

```bash
chattool setup hermes -e apple --model openai/gpt-5.4-mini
```

```bash
chattool setup hermes --installer /path/to/install.sh
```

```bash
chattool setup hermes --with-webui-env --webui-dir ./hermes-webui --start-webui
```

--------------------------------

### Start TUI with an initial prompt

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/opencode-cli-guide.md

Initiates the TUI session with a predefined prompt to guide the initial interaction.

```bash
opencode --prompt "先阅读这个仓库，再总结入口文件"
```

--------------------------------

### Generate Client Installer Package

Source: https://github.com/cubenlp/chattool/blob/master/skills/frp-configurator/SKILL.md

Creates a client installer package (`frpc_bundle.tar.gz`) based on an existing server configuration (`frps.toml`). This package is then used to set up the FRP client.

```bash
# Generate client installer based on my server config
bash scripts/pack_for_client.sh
# Then download 'frpc_bundle.tar.gz' to your client machine and run the install script inside.
```

--------------------------------

### ChatTool CC-Connect CLI Command Overview

Source: https://github.com/cubenlp/chattool/blob/master/docs/design/chattool-cc-cli-design.md

Lists the primary commands available in the first phase of the ChatTool CC-Connect CLI. These commands cover setup, initialization, starting, status checking, and log viewing.

```bash
chattool setup cc-connect
chattool cc setup   # alias
chattool cc init
chattool cc start
chattool cc status
chattool cc logs
chattool cc doctor
```

--------------------------------

### Run Chattool Zsh Setup Twice

Source: https://github.com/cubenlp/chattool/blob/master/tests/mock-cli-tests/setup/test_chattool_setup_zsh_basic.md

Demonstrates safe alias file updates and Zsh configuration by running the setup command twice. Ensures idempotency and correct management of alias blocks.

```sh
set HOME to tmp dir
write ~/.zshrc with existing content
mock which zsh exists
run chattool setup zsh --no-omz -I twice
assert ~/.zsh_aliases has one chattool zsh aliases block
assert ~/.zshrc has existing content and one alias source block
assert ~/.bash_profile has one zsh login block
```

--------------------------------

### Chattool Zsh Setup Default Plugins

Source: https://github.com/cubenlp/chattool/blob/master/tests/mock-cli-tests/setup/test_chattool_setup_zsh_basic.md

Verifies that in default mode (non-interactive), the setup command uses a predefined set of Oh My Zsh plugins without prompting for candidates.

```sh
mock interactive tty available
run chattool setup zsh --no-aliases --no-login-shell
assert plugin checkbox was not called
assert selected plugins equal all script plugins
```

--------------------------------

### Chattool Zsh Setup Interactive Mode

Source: https://github.com/cubenlp/chattool/blob/master/tests/mock-cli-tests/setup/test_chattool_setup_zsh_basic.md

Demonstrates interactive Zsh setup using the `-i` flag. This mode first prompts for base setup options (like aliases and login shell) and then for Oh My Zsh plugins.

```sh
mock interactive tty available
run chattool setup zsh --no-aliases --no-login-shell -i
assert checkbox default values include all script plugins
assert selected plugins equal git and zsh-autosuggestions
```

--------------------------------

### Chattool Zsh Setup Missing Git

Source: https://github.com/cubenlp/chattool/blob/master/tests/mock-cli-tests/setup/test_chattool_setup_zsh_basic.md

Tests the scenario where Git is missing, specifically when Oh My Zsh is enabled. The command should fail and suggest installing Git via apt.

```sh
mock which zsh exists and git missing
run chattool setup zsh --no-aliases --no-login-shell -I
assert exit code is non-zero
assert output includes sudo apt install git -y
```

--------------------------------

### Start a headless server with custom hostname and port

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/opencode-cli-guide.md

Configures the server to listen on a specific network interface and port.

```bash
opencode serve --hostname 127.0.0.1 --port 4096
```

--------------------------------

### Install ChatTool Skills

Source: https://github.com/cubenlp/chattool/blob/master/README.md

Add ChatTool skills to Codex, Claude, or OpenCode environments by running `chattool skill install`.

```bash
chattool skill install
```

--------------------------------

### Cursor Rule Example (.mdc)

Source: https://github.com/cubenlp/chattool/blob/master/docs/development-guide/skills-platform-compat.md

Example of a Cursor rule file (.mdc) with description and globs for file matching.

```markdown
---
description: Python 编码规范
globs:
  - "**/*.py"
---

- 公共函数必须加类型注解
- 优先使用小函数，保持可测试性
```

--------------------------------

### Generate Server Installer Package

Source: https://github.com/cubenlp/chattool/blob/master/skills/frp-configurator/SKILL.md

Creates a server installer package (`frps_bundle.tar.gz`) based on an existing local client configuration (`frpc.toml`). This package is then used to set up the FRP server.

```bash
# Generate server installer based on my client config
bash scripts/pack_for_server.sh
# Then upload 'frps_bundle.tar.gz' to your server and run the install script inside.
```

--------------------------------

### Install OpenCode CLI with Chatloop Plugin

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/opencode.md

Installs the OpenCode CLI, integrates the chatloop plugin and slash commands into OpenCode home, and installs its dependencies.

```bash
chattool setup opencode --install-only --plugin chatloop
```

--------------------------------

### Chattool Zsh Setup Interactive Base Options

Source: https://github.com/cubenlp/chattool/blob/master/tests/mock-cli-tests/setup/test_chattool_setup_zsh_basic.md

Shows interactive Zsh setup where the user is prompted for base configuration options first. If 'omz' is deselected, the plugin selection step is skipped.

```sh
mock interactive tty available
run chattool setup zsh -i
assert setup options checkbox default values are omz, aliases, login_shell
uncheck omz
assert plugin checkbox is not shown
```

--------------------------------

### Install AI Image Dependencies

Source: https://github.com/cubenlp/chattool/blob/master/README_en.md

Install the necessary dependencies for AI image generation features by running `pip install "chattool[images]"`.

```bash
pip install "chattool[images]"
```

--------------------------------

### Install CC-Connect CLI

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Installs or checks the 'cc-connect' CLI. Requires Node.js >= 20 and npm. Can show detailed logs with --log-level DEBUG.

```bash
chattool setup cc-connect
```

```bash
chattool setup cc-connect --log-level DEBUG
```

```bash
chattool cc setup
```

```bash
chattool cc init -i --quiet
```

```bash
chattool cc start --max-failures 5
```

--------------------------------

### Install OpenCode CLI Only

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/opencode.md

Installs or upgrades the OpenCode CLI without writing provider or model configurations.

```bash
chattool setup opencode --install-only
```

--------------------------------

### Setup Zsh Configuration

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Configures Zsh, oh-my-zsh, common plugins, powerlevel10k theme, and ~/.zsh_aliases, referencing QuickSetup-Ubuntu's zsh initialization.

```bash
chattool setup zsh
```

```bash
chattool setup zsh --no-omz
```

```bash
chattool setup zsh -i
```

--------------------------------

### Claude Code Skill Example

Source: https://github.com/cubenlp/chattool/blob/master/docs/development-guide/skills-platform-compat.md

Example of a Claude Code skill file with frontmatter and quick start instructions.

```markdown
---
name: arxiv-explore
description: Search and explore arXiv papers via ChatTool CLI.
allowed-tools:
  - Bash
---

## Quick Start

```bash
chattool explore arxiv daily -p ai4math
```
```

--------------------------------

### Setup OpenCode with Configuration

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Sets up OpenCode, prompting for configuration interactively or accepting parameters directly. Supports reusing 'chatenv' configurations and specifying plugins.

```bash
chattool setup opencode
```

```bash
chattool setup opencode --log-level DEBUG
```

```bash
chattool setup opencode --base-url "https://example.com/openai" --api-key "sk-xxx" --model "gpt-4.1-mini"
```

```bash
chattool setup opencode -e work
```

```bash
chattool setup opencode -e ~/.chatarch/envs/OpenAI/work.env
```

```bash
chattool setup opencode -e work --plugin auto-loop
```

--------------------------------

### Setup Workspace

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Initializes a workspace for human-AI collaboration, multi-task concurrency, and knowledge accumulation. It generates a standard project skeleton.

```bash
chattool setup workspace
```

```bash
chattool setup workspace ~/workspace/demo
```

```bash
chattool setup workspace ~/workspace/demo --language en
```

--------------------------------

### Enable Chatloop Plugin during OpenCode Setup

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/opencode.md

Installs the chatloop plugin assets, prepares its directory, installs dependencies, and adds its file path to the OpenCode configuration.

```bash
chattool setup opencode --plugin chatloop
```

--------------------------------

### Initialize ChatTool Workspace

Source: https://github.com/cubenlp/chattool/blob/master/README.md

Set up a collaborative human-AI workspace skeleton using `chattool setup workspace`. It defaults to using `projects/` for execution and supports enabling OpenCode loop-aware templates with `--with-opencode-loop`.

```bash
chattool setup workspace
```

```bash
chattool setup workspace --with-opencode-loop
```

--------------------------------

### Start Lark Bot for Real-time Interaction

Source: https://github.com/cubenlp/chattool/blob/master/examples/demo/lark/lark_02_receiving.ipynb

Initializes and starts a LarkBot in the background to listen for messages and respond to commands. This setup includes handlers for `/help`, `/status`, and a general message echo.

```python
from chattool.tools.lark import LarkBot

bot_live = LarkBot()

@bot_live.command("/help")
def help_cmd(ctx):
    ctx.reply("📖 指令列表：/help  /status")

@bot_live.command("/status")
def status_cmd(ctx):
    import time
    ctx.reply(f"✅ 在线 | {time.strftime('%H:%M:%S')}")

@bot_live.on_message
def echo(ctx):
    ctx.reply(f"📨 收到：{ctx.text}")

# 后台启动（不阻塞 Notebook）
bot_live.start_background()
print("🚀 机器人已启动，发消息试试吧！")
```

--------------------------------

### Start Interactive Codex Session

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/codex-cli-guide.md

Initiate an interactive chat session with Codex. You can provide an initial prompt to guide the conversation.

```bash
codex
```

```bash
codex "帮我分析这个仓库的 CLI 结构"
```

--------------------------------

### Initialize arXiv Client and Fetcher in Python

Source: https://github.com/cubenlp/chattool/blob/master/skills/arxiv-explore/SKILL.md

Demonstrates initializing the ArxivClient and DailyFetcher from the chattool.explore.arxiv library, and accessing predefined presets.

```python
from chattool.explore.arxiv import ArxivClient, DailyFetcher, PRESETS, build_query, ArxivQuery

# --- Presets ---
preset = PRESETS["ai4math"]
fetcher = DailyFetcher()

```

--------------------------------

### GitHub Repository API Endpoints

Source: https://github.com/cubenlp/chattool/blob/master/docs/design/explore-github.md

Examples of GET requests to the GitHub repository API for fetching metadata, README, releases, issues, topics, and contributors.

```http
GET /repos/{owner}/{repo}                    # 元数据
```

```http
GET /repos/{owner}/{repo}/readme             # README（base64）
```

```http
GET /repos/{owner}/{repo}/releases           # Releases
```

```http
GET /repos/{owner}/{repo}/issues             # Issues
```

```http
GET /repos/{owner}/{repo}/topics             # Topics
```

```http
GET /repos/{owner}/{repo}/contributors       # 贡献者
```

--------------------------------

### Example FRP Client Configuration

Source: https://github.com/cubenlp/chattool/blob/master/skills/frp-configurator/SKILL.md

A sample `frpc.toml` file demonstrating how to connect to an FRP server and expose a local service (SSH) to the remote server.

```toml
serverAddr = "203.0.113.10"
serverPort = 7000

auth.method = "token"
auth.token = "secure_token_123"

# Expose local SSH (Port 22) to Remote Server (Port 6000)
[[proxies]]
name = "ssh-my-laptop"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000
```

--------------------------------

### GitHub Search API Endpoints

Source: https://github.com/cubenlp/chattool/blob/master/docs/design/explore-github.md

Examples of GET requests to the GitHub search API for repositories, code, and users. These endpoints are used for various search queries.

```http
GET /search/repositories?q=language:python&sort=stars&order=desc&per_page=30
```

```http
GET /search/code?q=filename:Dockerfile+user:torvalds
```

```http
GET /search/users?q=location:beijing+followers:>1000
```

--------------------------------

### Simulating Trending Repositories

Source: https://github.com/cubenlp/chattool/blob/master/docs/design/explore-github.md

An example GET request to the search API used to simulate the trending repositories feature by querying for recently created repositories sorted by stars.

```http
GET /search/repositories?q=created:>2025-03-12&sort=stars&order=desc
```

--------------------------------

### Render Suggested Commands

Source: https://github.com/cubenlp/chattool/blob/master/docs/development-guide/chatstyle.en.md

Use this helper function for displaying suggested commands when a setup flow requires sudo but the `--sudo` switch is not provided. This ensures consistent display of alternative actions.

```python
from chatstyle.render import render_suggested_commands

commands = ["sudo apt update", "sudo apt upgrade"]
render_suggested_commands(commands)
```

--------------------------------

### Start ChatTool MCP Service

Source: https://github.com/cubenlp/chattool/blob/master/docs/mcp/index.md

Manually start the ChatTool MCP service for debugging or direct use. The first command starts it in STDIO mode, while the second starts it in HTTP mode on port 8000 for remote access.

```bash
# 启动 MCP 服务 (STDIO 模式)
chattool mcp start
```

```bash
# 启动 MCP 服务 (HTTP 模式，用于远程调用)
chattool mcp start --transport http --port 8000
```

--------------------------------

### Set and Get Individual Environment Values

Source: https://github.com/cubenlp/chattool/blob/master/README_en.md

Set or get individual configuration values using `chatenv set` and `chatenv get`.

```bash
chatenv set OPENAI_API_KEY=sk-xxx
```

```bash
chatenv get OPENAI_API_KEY
```

--------------------------------

### Debug Node.js Installation

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/codex.md

Enables detailed logging for the Node.js installation process, including runtime detection, shell rc updates, and nvm install phases.

```bash
chattool setup nodejs --log-level DEBUG
```

--------------------------------

### Initialize and Build PyPI Packages

Source: https://github.com/cubenlp/chattool/blob/master/skills/practice-make-perfact/references/cli-reference.md

Commands for initializing, building, checking, probing, and uploading PyPI packages using the chattool pypi command.

```bash
chattool pypi init <name>
```

```bash
chattool pypi init <name> -t chatarch --project-dir ./<name>
```

```bash
chattool pypi build --project-dir .
```

```bash
chattool pypi check --project-dir .
```

```bash
chattool pypi probe <name>
```

```bash
chattool pypi upload --project-dir .
```

```bash
chatpypi <name> -t chatarch --project-dir ./<name>
```

--------------------------------

### ChatTool Agent CLI Installer

Source: https://context7.com/cubenlp/chattool/llms.txt

Commands for installing or upgrading AI agent CLIs (Codex, Claude, OpenCode, Hermes) and setting up collaboration workspaces. Also includes installing ChatTool skills.

```bash
# Install / upgrade agent CLIs
chattool setup codex
chattool setup claude
chattool setup opencode
chattool setup hermes            # wraps official installer; WebUI is opt-in
chattool setup hermes --install-only   # pure install/upgrade, no config write
```

```bash
# Create a collaboration workspace
chattool setup workspace
chattool setup workspace --with-opencode-loop   # OpenCode loop-aware variant
```

```bash
# Install ChatTool skills into an agent
chattool skill install           # auto-detects Codex / Claude / OpenCode
```

--------------------------------

### Setup Codex with API Key

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Sets up Codex, prompting for API key interactively or accepting it directly via --api-key. Supports reusing existing 'chatenv' configurations with -e.

```bash
chattool setup codex
```

```bash
chattool setup codex --log-level DEBUG
```

```bash
chattool setup codex --api-key "sk-xxx"
```

```bash
chattool setup codex -e work
```

```bash
chattool setup codex -e ~/.chatarch/envs/OpenAI/work.env
```

```bash
chattool setup codex --api-key "sk-xxx" --base-url "https://example.com/openai" --model "gpt-5.4"
```

--------------------------------

### Windsurf Rules Example

Source: https://github.com/cubenlp/chattool/blob/master/docs/development-guide/skills-platform-compat.md

Example of Windsurf rules file, specifying development guidelines.

```markdown
# Windsurf Rules

- 改动范围最小化
- 行为变更时同步更新测试
```

--------------------------------

### Initialize Provider Credentials

Source: https://github.com/cubenlp/chattool/blob/master/skills/cert-manager/SKILL.md

Configure provider credentials using typed environment profiles before applying certificates. Supported providers include 'aliyun' and 'tencent'.

```bash
chatenv init -t ali
chatenv init -t aliyun
chatenv init -t tencent
chatenv cat -t ali
```

--------------------------------

### Complete Chat Tool Usage Example

Source: https://github.com/cubenlp/chattool/blob/master/docs/chat.md

Demonstrates the full lifecycle of using the Chat tool, including creating a chat instance, setting system messages, performing synchronous and asynchronous user queries, handling streaming responses, saving the conversation, and printing debug information. Requires the 'chattool' library and an environment variable for default model configuration.

```python
import asyncio
from chattool import Chat
async def complete_example():
    """完整的使用示例"""
    
    # 1. 创建对话（从环境变量读取默认配置）
    chat = Chat(model="gpt-4o-mini")
    
    # 2. 设置系统消息
    chat.system("你是一个有用的AI助手，能够回答各种问题。")
    
    # 3. 进行对话
    print("=== 同步对话 ===")
    response = chat.user("什么是人工智能？").get_response()
    print(f"AI: {response.content}")
    
    # 4. 异步对话
    print("\n=== 异步对话 ===")
    response = await chat.user("AI的发展历史如何？").async_get_response()
    print(f"AI: {response.content}")
    
    # 5. 流式响应
    print("\n=== 流式响应 ===")
    print("AI: ", end='')
    async for chunk in chat.user("请写一首关于技术的诗").async_get_response_stream():
        print(chunk.content, end='', flush=True)
    print()
    
    # 6. 保存对话
    chat.save("example_conversation.jsonl")
    
    # 7. 显示调试信息
    print("\n=== 调试信息 ===")
    chat.print_debug_info()

# 运行完整示例
if __name__ == "__main__":
    asyncio.run(complete_example())
```

--------------------------------

### OpenCode Configuration using Environment Profile

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/opencode.md

Sets up OpenCode by reusing existing OpenAI configurations stored in a 'work' environment profile.

```bash
chattool setup opencode -e work
```

--------------------------------

### Manage Environment and Profiles

Source: https://github.com/cubenlp/chattool/blob/master/skills/practice-make-perfact/references/cli-reference.md

Commands for initializing, listing, viewing, creating, saving, using, deleting, and testing environment profiles.

```bash
chatenv init -t <type>
```

```bash
chatenv list
```

```bash
chatenv cat -t <type>
```

```bash
chatenv new -t <type> work
```

```bash
chatenv save -t <type> work
```

```bash
chatenv use -t <type> work
```

```bash
chatenv delete -t <type> work
```

```bash
chatenv paste --stdin --profile work
```

```bash
chatenv test -t <type>
```

--------------------------------

### Start Local Service

Source: https://github.com/cubenlp/chattool/blob/master/docs/tools/svg2gif.md

Starts a local service to convert SVG animations to GIF. Requires chromedriver to be running.

```APIDOC
## Start Local Service

Starts a local service to convert SVG animations to GIF using chromedriver.

### Command
```bash
chattool serve svg2gif --chromedriver-url http://127.0.0.1:9515
```

### Environment Variable
Alternatively, set the CHATTOOL_CHROMEDRIVER_URL environment variable:
```bash
export CHATTOOL_CHROMEDRIVER_URL=http://127.0.0.1:9515
chattool serve svg2gif
```
```

--------------------------------

### Install chattool Package

Source: https://github.com/cubenlp/chattool/blob/master/README_en.md

Install the chattool package using pip. Ensure you are using Python 3.10 or higher.

```bash
pip install chattool --upgrade
```

--------------------------------

### Start Chromedriver Service

Source: https://github.com/cubenlp/chattool/blob/master/docs/tools/svg2gif.md

Before using the svg2gif tool, ensure chromedriver is running. This command starts the service on the default port.

```bash
chromedriver --port 9515
```

--------------------------------

### Manage Certificates via Server-Client

Source: https://github.com/cubenlp/chattool/blob/master/skills/cert-manager/SKILL.md

Start a certificate server, and then use the client to apply for, list, or download certificates. Requires a shared token for authentication.

```bash
chattool serve cert --token "my-secret-token" --provider aliyun
chattool client cert apply -d example.com --token "my-secret-token" --server http://server:8000
chattool client cert list --token "my-secret-token" --server http://server:8000
chattool client cert download example.com --token "my-secret-token" --server http://server:8000
```

--------------------------------

### Convenience Wrapper for Package Initialization

Source: https://github.com/cubenlp/chattool/blob/master/skills/python-package-starter/SKILL.md

A shorthand command to initialize a Python package, equivalent to `chattool pypi init`. It can also trigger the interactive wizard if a package name is omitted.

```bash
chatpypi mychat --description "My chat package"
```

--------------------------------

### Server Response Example

Source: https://github.com/cubenlp/chattool/blob/master/docs/tools/svg2gif.md

Example JSON response from the /svg2gif POST endpoint, indicating success and providing GIF details.

```json
{
  "ok": true,
  "gif_path": "/tmp/chattool-svg2gif/termcap.gif",
  "frames": 100,
  "duration_ms": 8347
}
```

--------------------------------

### Interactive OpenCode Configuration

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/opencode.md

Initiates an interactive setup for OpenCode, prompting for base URL, API key, and default model.

```bash
chattool setup opencode
```

--------------------------------

### Lark CLI Setup with Debug Logging

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/lark-cli.md

Enables detailed logging during the Lark CLI setup process for debugging purposes.

```bash
chattool setup lark-cli --log-level DEBUG
```

--------------------------------

### Setup Docker Environment

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Checks Docker, Docker Compose, and user group status. Can execute commands with sudo if specified with --sudo -i.

```bash
chattool setup docker
```

```bash
chattool setup docker --log-level DEBUG
```

```bash
chattool setup docker --sudo -i
```

--------------------------------

### Manage ChatTool Skills

Source: https://github.com/cubenlp/chattool/blob/master/skills/practice-make-perfact/references/cli-reference.md

Commands for listing, installing, and managing skills within ChatTool. Specify the source directory and platform for installation.

```bash
chattool skill list --source ChatTool/skills
```

```bash
chattool skill install <name> --source ChatTool/skills --platform codex --force
```

```bash
chattool skill install --all --source ChatTool/skills --dest /tmp/skills --platform codex --force
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/cubenlp/chattool/blob/master/docs/mcp/index.md

Installs the uv package manager, recommended for running Python tools efficiently. Run this command in your terminal.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### ChatEnv Cat Command Flow

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/chatenv-provider-discovery.md

Illustrates the runtime flow for the `chatenv cat -t foo` command, showing how configuration providers are loaded and configuration details are retrieved.

```text
chatenv cat -t foo
  -> 进入 chatenv.cli
  -> load_config_providers()
  -> entry_points(group="chatenv.configs")
  -> ep.load() imports chatfoo.config
  -> FooConfig 注册到 BaseEnvConfig._registry
  -> resolve_config_types(("foo",)) 匹配 _aliases / _storage_dir / _title
  -> EnvStore 读取 ~/.chatarch/envs/Foo/.env
  -> 按 FooConfig.get_fields() 输出字段
```

--------------------------------

### Paste and Import Environment Configuration

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Import environment configuration from copied text or a file. Use '--stdin' to read from standard input and '--profile' to specify a profile name.

```bash
chatenv paste
```

```bash
chatenv paste --stdin --yes < openai.env
```

```bash
chatenv paste --stdin --profile work --yes < openai.env
```

--------------------------------

### Install Chrome and Chromedriver

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/chrome.md

Automatically detects installed Chrome version and downloads matching Chromedriver. Use interactive mode for custom paths or step-by-step confirmation.

```bash
chattool setup chrome
```

```bash
chattool setup chrome -i
```

```bash
chattool setup chrome --interactive
```

--------------------------------

### Get Streaming Asynchronous Chat Response

Source: https://github.com/cubenlp/chattool/blob/master/docs/chat.md

Receive responses from the chat model in a streaming fashion asynchronously. Iterate over the `async_get_response_stream` to get content chunks as they become available.

```python
import asyncio

async def streaming_example():
    chat = Chat()
    
    # 异步流式响应
    async for chunk in chat.user("写一首关于春天的诗").async_get_response_stream():
        print(chunk.content, end='', flush=True)
    print()  # 换行

# 运行流式示例
asyncio.run(streaming_example())
```

--------------------------------

### Manage Python Packages with ChatTool PyPI

Source: https://github.com/cubenlp/chattool/blob/master/README.md

The `chattool pypi` command suite allows for initializing, building, checking, uploading, and probing Python packages. Use `chattool pypi init <name>` to start a new package, with `-t chatarch` for a specific template. Interactive initialization is available with `-i`.

```bash
chattool pypi init mychat
```

```bash
chattool pypi init mycli -t chatarch
```

```bash
chattool pypi init -i
```

--------------------------------

### Download SSL Certificate with Client

Source: https://github.com/cubenlp/chattool/blob/master/docs/client.md

Download specified certificate files (cert.pem, privkey.pem, fullchain.pem) to a local directory using the client tool. The domain can be specified, or it will be prompted interactively if omitted.

```bash
chattool client cert download example.com -o ./my-certs --token my-secret-token
chattool client cert download
```

--------------------------------

### Setup Codex Using Environment Profile

Source: https://github.com/cubenlp/chattool/blob/master/docs/env/codex.md

Sets up Codex by reusing an existing OpenAI configuration profile stored in `chatenv`. The profile can be specified by name or by its `.env` file path.

```bash
chattool setup codex -e work
```

```bash
chattool setup codex -e ~/.chatarch/envs/OpenAI/work.env
```

--------------------------------

### Mock Script for Non-TTY Interactive Flow

Source: https://github.com/cubenlp/chattool/blob/master/tests/mock-cli-tests/codex/test_chattool_setup_codex_basic.md

This pseudocode describes the test setup for the Chattool Codex setup command when run in a non-interactive terminal (no TTY). It verifies that the command fails fast and does not trigger an implicit interactive flow when required keys are missing.

```pseudocode
prepare empty temp HOME
stub node/npm related checks
stub non-interactive terminal
run chattool setup codex
assert command exits with error
assert no prompt is called
```

--------------------------------

### Codex CLI Practical Templates

Source: https://github.com/cubenlp/chattool/blob/master/docs/blog/agent-cli/codex-cli-guide.md

Quick-start templates for common Codex CLI workflows.

```bash
codex "先阅读这个仓库，再告诉我最关键的开发入口"
```

```bash
codex exec -C /path/to/repo "总结 src/ 下各模块职责"
```

```bash
codex review --uncommitted "优先关注行为回归和漏掉的文档"
```

```bash
codex resume --last
```

```bash
codex --no-alt-screen --search
```