Skip to content
BranchesTags

Repository files navigation

nac

中文 | English

CI Release Go Reference License: MIT

一个快速、单文件二进制的命令行客户端，用于 new-api 网关。以 nac 二进制形式发布。

功能特性 • 安装 • 快速开始 • 登录 • 命令 • 使用-nac-编写脚本

$ nac chat "explain Server-Sent Events in one paragraph"
Server-Sent Events (SSE) is a unidirectional streaming protocol over HTTP
where the server pushes UTF-8 text events to the client as soon as they
are ready...
(prompt=12, completion=87, total=99)

管理你的网关账户、运行 AI 推理，并把一切接入 shell 脚本 —— 无需浏览器，也无需解析自然语言。

功能特性

  • 完整覆盖 new-api —— 聊天、消息、图像、嵌入、模型、token、用量、充值、邀请、签到、分组
  • 流式优先 —— 为 OpenAI 和 Anthropic 协议提供增量 SSE；脚本化可用 --no-stream
  • 交互式 REPL —— nac chat -i 提供带历史记录和多行输入的会话
  • 多配置档 —— 通过 --profile 或 nac config use 在 dev/staging/prod 网关之间切换
  • 密钥存于系统钥匙串 —— 默认使用 OS 钥匙串，在无头机器上回退到 0600 权限的文件
  • 管道友好 —— --json 输出单个 JSON 值；退出码 2/3/4/5/6/7 便于 shell 分支判断
  • 动态 shell 补全 —— bash、zsh、fish、PowerShell；可对实时的配置档/token/分组/模型名进行 Tab 补全

安装

Homebrew (macOS 与 Linux)

brew install Xbang0222/tap/nac

预编译二进制

从 releases 页面 选择你的平台 —— darwin/linux/windows × amd64/arm64。

从源码安装

go install github.com/Xbang0222/nac/cmd/nac@latest

Note

需要 Go 1.25.10 或更新版本。

快速开始

# 1. Authenticate
nac login --endpoint https://your-newapi.example.com

# 2. Confirm the session
nac whoami

# 3. One-shot chat
nac chat "summarize the SOLID principles"

# 4. Pipe stdin as the prompt
git diff | nac chat -m claude-sonnet-4-6 -s "review this diff"

# 5. Interactive session
nac chat -i -m gpt-4o-mini

# 6. Inspect your spend
nac usage --from 2026-05-01 --group --top 5

登录

浏览器流程 (默认，推荐):

nac login --endpoint https://api.example.com

这会打开你的默认浏览器跳转到 <endpoint>/cli-login，让你使用服务器支持的任意方式 (密码、OAuth、Passkey、2FA) 登录，并通过一个短暂存活的 127.0.0.1 回环将访问 token 返回给 CLI。token 会存储在 OS 钥匙串中 (或回退为 0600 权限的文件)。对于无头/SSH 会话，传入 --no-browser 仅打印 URL 而不尝试启动任何程序。

CI / 脚本 (非交互):

nac login --endpoint https://api.example.com \
    --email me@example.com --password "$NEWAPI_PASSWORD" \
    --profile prod --no-pick-key

配置

nac 在 ~/.config/newapi/config.yaml 维护一份小型 YAML 配置 (符合 XDG 规范；可用 NEWAPI_CONFIG_HOME 覆盖)。密钥单独存储在 OS 钥匙串中 —— 配置文件只保存指向它们的引用。

配置档

一个配置档 (profile) 由端点 + 默认模型 + 凭据对组成:

nac config create work --endpoint https://api.work.example.com --model gpt-4o-mini
nac config list
nac config use work
nac --profile work chat "hi"   # per-invocation override
nac config delete work

环境变量

变量 用途
NEWAPI_ENDPOINT 覆盖网关地址
NEWAPI_ACCESS_TOKEN 账户级 token (供 /api/* 使用)
NEWAPI_API_KEY sk-xxx 推理密钥 (供 /v1/* 使用)
NEWAPI_PROFILE 覆盖当前激活的配置档
NEWAPI_CONFIG_HOME 覆盖配置目录
XDG_CONFIG_HOME 标准 XDG 覆盖 —— nac 会在 $XDG_CONFIG_HOME/newapi 下查找
NO_COLOR / FORCE_COLOR 禁用 / 强制 ANSI 颜色

Tip

环境变量优先于配置档字段 —— 在仓库旁放一个 .envrc，你的 CI 脚本就永远不必碰 YAML 配置。

命令

分组 命令
AI 调用 chat, messages, images, embed, models
认证 login, logout, whoami
Token token list, token show, token create, token update, token enable, token disable, token delete, token use
计费 usage, usage stat, topup list, invites, checkin, checkin status
分组 group list, group models
配置档 config list, config show, config use, config set, config create, config delete
工具 version, completion

对任意子命令运行 nac <command> --help 可查看完整的旗标列表。

全局旗标

旗标 含义
--profile <name> 为本次调用切换配置档
--endpoint <url> 覆盖端点 URL
--config <path> 覆盖配置文件路径
--json 向 stdout 输出单个 JSON 值
--plain 禁用颜色、边框和加载动画
--no-input 从不提示；必填旗标必须显式传入
--no-stream 为 chat / messages 禁用流式
--verbose / -v 将请求细节记录到 stderr
--version / -V 打印版本并退出

AI 调用 —— 短别名

  • chat / messages: -m / --model, -s / --system, -i / --interactive
  • images: -m / --model, -n / --num, -o / --output
  • embed: -m / --model

使用 nac 编写脚本

nac 的设计让 AI 智能体和 shell 管道无需解析自然语言即可组合调用它。有五条约定让这一切成为可能:

  1. --json 向 stdout 返回单个 JSON 值 —— 绝不是 NDJSON，也绝不带横幅。设置 --json 时，流式命令会先缓冲。
  2. --no-input 禁用所有交互式提示。 缺少必填参数 → 以非零码退出，绝不挂起管道。
  3. 退出码是约定的一部分 (见下表)。2 = 输入错误，3 = token 错误，5 = 限流，6 = 上游，7 = 网络。
  4. 上游错误消息原样透传，因此仅凭日志即可调试故障。
  5. NO_COLOR=1、--plain 以及被管道接收的 stdout 都会丢弃 ANSI —— nac cmd | grep ... 无需任何旗标即可工作。

模式: 选出某分组中最便宜的模型

MODEL=$(nac --json group models default \
  | jq -r '[.[] | select(.model_price > 0)] | min_by(.model_price) | .model_name')
nac --no-input --no-stream chat -m "$MODEL" "summarize this README" < README.md

模式: 幂等的 token 引导

ID=$(nac --json token list --search agent | jq -r '.[0].id // empty')
if [ -z "$ID" ]; then
  ID=$(nac --json --no-input token create agent --groups default --models "" \
    | jq -r .id)
fi
nac token use "$ID"

模式: 捕获特定的失败类型

out=$(nac --json --no-input chat -m gpt-4o-mini "hi" 2>&1) || rc=$?
case "${rc:-0}" in
  0)   echo "ok: $out" ;;
  3)   echo "auth failed — re-run nac login" ;;
  5)   echo "rate limited — back off" ;;
  6|7) echo "gateway problem — retry later" ;;
  *)   echo "unexpected: $out" ;;
esac

模式: 供 AI 自省的接口

nac --help                       # top-level commands
nac <command> --help             # flags + examples for any subcommand
nac --json group list            # available groups
nac --json group models default  # available models with pricing
nac --json token list            # current tokens

每个只读的 /api/* 命令都支持 --json。设置 --json 时，变更类命令会返回变更后的状态，因此你可以把 create | jq .id 直接接入 use $ID。

shell 补全

nac completion zsh > "${fpath[1]}/_nac"
nac completion bash > /usr/local/etc/bash_completion.d/nac
nac completion fish > ~/.config/fish/completions/nac.fish
nac completion powershell | Out-String | Invoke-Expression

补全不止于静态旗标名 —— nac 为以下内容提供了动态补全:

  • --profile <Tab> 以及每个 config use|delete|show|set 的参数 → 读取 config.yaml
  • token show|delete|enable|disable|update|use <Tab> → 实时 token ID (含名称)
  • --groups <Tab> (用于 token create / token update) → 实时分组
  • --model <Tab> (用于 chat、messages、images、embed、usage) → 实时模型名
  • group models <Tab> → 实时分组

Note

若缺少认证信息，依赖网络的补全会静默地空操作，因此未配置的 shell 在按 Tab 时绝不会挂起。

退出码

码 含义
0 成功
1 通用 / 意外错误
2 错误请求 (HTTP 400，或业务逻辑 {success:false} 且无认证/限流提示)
3 未授权 (HTTP 401，或 HTTP 200 但消息含认证关键词)
4 禁止访问 (HTTP 403)
5 被限流 (HTTP 429)
6 上游服务器错误 (HTTP 5xx)
7 网络错误 (超时、DNS、重置)

Important

new-api 偶尔会对业务错误 (无效 token、会话过期……) 返回 HTTP 200 并带 {success:false}。nac 会对服务器消息进行关键词匹配，以选择 2/3/5，让脚本仍能基于 $? 进行分支判断。

开发

make build       # compile ./nac with embedded version
make install     # go install into $GOBIN
make test        # go test -race -count=1 ./...
make lint        # go vet + gofmt -l
make clean       # rm binary + dist/

或者无需构建直接迭代:

go run ./cmd/nac <subcommand> [flags]

Note

架构细节、双轨认证说明以及 DTO 陷阱见 CLAUDE.md。

About

Command-line client for new-api gateways

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages