# taichu CLI

<p>
  <img src="https://cdn.jsdelivr.net/npm/@taichuai/taichu-cli/assets/TaiChuCloudLogo.png" alt="taichuCloud" width="220" />
</p>

> Official command-line tool for [Zidong Taichu Cloud platform](https://cloud.zidongtaichu.com/). Discover models, check usage, create API keys, and diagnose local setup from a terminal or an AI agent runtime.

![Version](https://img.shields.io/badge/version-1.0.6-blue)
![Node](https://img.shields.io/badge/node-%3E%3D18-green)
![License](https://img.shields.io/badge/license-Apache--2.0-green)

**English** · [中文](https://cdn.jsdelivr.net/npm/@taichuai/taichu-cli/README.md)

![taichu CLI REPL welcome screen](https://cdn.jsdelivr.net/npm/@taichuai/taichu-cli/assets/TaichuCLI.png)

---

## Features

- **Interactive and one-shot modes**: run `taichu` with no arguments for a REPL, or pass a command for scripts, CI, and agent tools.
- **Agent-ready contract**: commands support `--format json`, standardized exit codes, parseable JSON errors, and `--quiet` for exit-code-only checks.
- **Model and usage workflows**: browse models, inspect model metadata, search by keyword, and review Free Tier, Token Plan, and PAYG usage.
- **Native credential storage**: credentials are stored in the OS keychain when available, with an encrypted file fallback. No `keytar` or native Node binding is required.
- **Self-documenting command tree**: every command supports `--help`; generated help is the canonical syntax reference.

---

## Installation

### npm

```bash
npm install -g @taichuai/taichu-cli
```

Verify the install:

```bash
taichu version
```

If you see `command not found: taichu` after installation, the npm global bin directory is not in your PATH. Run the command for your shell:

| Shell | Command                                                                                    |
| ----- | ------------------------------------------------------------------------------------------ |
| bash  | `echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc` |
| zsh   | `echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc`   |

---

## Quick Start

### For Developers

```bash
# 1. Log in with OAuth Device Flow
taichu auth login

# 2. List available models
taichu models list

# 3. Inspect a model
taichu models info taichu_o1

# 4. Try model invocation
text generation: taichu models invoke --request '{"messages":[{"content":"Hello","role":"user"}]}'
visual question answering: taichu models invoke --request '{"messages":[{"content":[{"type":"text","text":"What breed is this cat?"},{"type":"image_url","image_url":{"url":"https://s3.wair.ac.cn/alluxio/publish-data/system-config/question_answer_2.png"}}],"role":"user"}]}'
text-to-image: taichu models invoke --request '{"input_text":"Generate a cartoon girl avatar"}'

# 5. Review invocation statistics
taichu models usage

# 6. Check auth, network, config, and local environment
taichu doctor
```

Running `taichu` with no arguments opens the REPL. The REPL uses the same command tree as one-shot mode and adds readline history, tab completion, and rich terminal tables.

### For AI Agents

Use one-shot commands and request JSON explicitly:

```bash
taichu auth status --format json
taichu models list --format json
taichu keys list --format json
taichu doctor --format json
```

---

## Examples

Browse available models and inspect their modality, free tier quota, and pricing from the terminal:

![taichu CLI models list](https://cdn.jsdelivr.net/npm/@taichuai/taichu-cli/assets/model_list.png)

Run diagnostics to verify authentication, network access, configuration, and shell completion:

![taichu CLI doctor diagnostics](https://cdn.jsdelivr.net/npm/@taichuai/taichu-cli/assets/doctor.png)

---

## Commands

| Area        | Commands                                                  | Common flags                                                                                                  |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Auth        | `auth login`, `auth logout`, `auth status`                | `--init-only`, `--complete`, `--timeout`, `--format`                                                          |
| Models      | `models list`, `models info`                              | `--query`, `--type`, `--page`, `--per-page`, `--format`                                                       |
| Usage       | `models usage`                                            | `--user`, `--model`, `--api-key`, `--from`, `--to`, `--page`, `--per-page`, `--format`                        |
| Invocation  | `models invoke`                                           | `--request`, `--file`, `--output`, `--model`, `--stream`, `--enable-thinking`, `--hide-reasoning`, `--format` |
| Keys        | `keys list`, `keys create`, `keys disable`, `keys delete` | `--page`, `--per-page`, `--desc`, `--yes`, `--format`                                                         |
| Config      | `config list`, `config get`, `config set`, `config unset` | `--format`                                                                                                    |
| Diagnostics | `doctor`                                                  | `--format`                                                                                                    |
| Shell       | `completion install`, `completion generate`               | `--shell`                                                                                                     |
| Version     | `version`                                                 |                                                                                                               |

Use help for exact syntax:

```bash
taichu --help
taichu models --help
taichu models list --help
```

---

## Output and Exit Codes

Output format resolution order:

1. `--format` flag
2. `output.format` from config
3. TTY detection: table in an interactive terminal, JSON when piped or captured

```bash
taichu models list
taichu models list --format json
taichu models list --format text
taichu --quiet doctor
```

Exit codes:

|  Code | Meaning                              |
| ----: | ------------------------------------ |
|   `0` | Success                              |
|   `1` | General or usage error               |
|   `2` | Authentication error                 |
|   `3` | Network error                        |
|   `4` | Configuration or parameter error     |
|   `5` | Rate limited                         |
|   `6` | Server error                         |
|   `7` | Resource not found                   |
|   `8` | Reserved for an incomplete operation |
| `130` | User interrupted                     |

JSON errors follow a stable shape:

```json
{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Not authenticated. Run: taichu login",
    "exit_code": 2
  }
}
```

For automation, prefer `--format json` and treat table output as human-only.

Example JSON output:

```json
{
  "models": [
    {
      "model_id": 133,
      "model_code": "taichu_llm"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
```

---

## Authentication

`taichu auth login` uses OAuth 2.0 Device Authorization Grant with PKCE.

Interactive login:

```bash
taichu auth login
```

Credentials are stored in the OS keychain when available. If keychain access is unavailable, the CLI falls back to an encrypted local credential file. Set `TAICHU_KEYRING=plaintext` to force plaintext file storage for debugging; `no`, `0`, `false`, and `off` also skip keychain access.

---

## Configuration

taichu CLI uses one global config file:

```text
~/.taichu/config.json
```

Public configuration keys:

| Key             | Values                          | Default |
| --------------- | ------------------------------- | ------- |
| `output.format` | `auto`, `table`, `json`, `text` | `auto`  |

```bash
taichu config set output.format json
taichu config get output.format
taichu config list
taichu config unset output.format
```

---

## License

This project is licensed under the [Apache-2.0 License](LICENSE).