客户端与提供商 client / provider / restore-all 子命令
管理客户端
与控制台「客户端」页等价的终端操作:
astra client list # 列出全部客户端与接管状态
astra client status claude-code # 查看单个客户端详情
astra client enable codex --provider deepseek --model deepseek-chat
astra client enable codex --provider deepseek --token 工作电脑 # 指定写入的令牌
astra client disable codex # 停用并还原配置
客户端标识:codex、claude-code、gemini-cli、opencode、claude-desktop、grok-build、pi、hermes-agent、minimax-code、copilot-cli、vscode-copilot、crush、qwen-code、droid、kimi-code、zed、vscode-insiders、vscodium、omp、mimo-code、deepseek-harness、workbuddy、workbuddy-ai、muse-code、nextcowork、paseo、zcode、tkcode。
启用流程与控制台一致:先备份(首次修改前的备份永久保留),再写入网关地址与令牌。--provider 使用提供商的 ID 或名称(astra provider list 可查);--token 使用令牌的 ID 或名称(astra token list 可查),不传时沿用该客户端当前的令牌,从未设置过则使用默认令牌。
查看令牌
列出全部令牌:是否默认、是否启用、使用它的客户端、今日消耗 / 今日 Token 与累计消耗。命令不会输出令牌明文;新建、重置、删除令牌以及复制明文请在控制台的令牌页 完成。
禁用即还原 disable 会撤销 Astra 写入的配置项。若某些项在接管后被你手动改过(漂移),
命令会列出它们并要求确认是否强制还原——与控制台行为一致。
管理提供商
astra provider list
astra provider templates # 查看可用模板 id
astra provider add --template deepseek --key sk-xxx --name 我的DeepSeek
astra provider add --template openrouter --variant cn --key sk-or-xxx
astra provider remove < i d >
--template 与 --variant 取值见 astra provider templates。更细的配置(价格表、倍率、代理、请求头、订阅账号)请用控制台。
从其他应用导入
astra provider import # 只列出 CC Switch / Alma / Claude Code / Codex / Magpie 里发现的提供商,不写入
astra provider import --from magpie # 只看某个来源:cc-switch | alma | claude-code | codex | magpie
astra provider import --yes # 导入状态为 new 的条目
astra provider import --yes --only magpie:relay --only codex:my-relay # 只导入指定的 ref
列表里的 REF 用于 --only。来源只读,API Key 由服务端直接读取并加密保存,不经过 CLI;已存在(同地址同 Key)与无法导入的条目会被拒绝。控制台里的导入面板行为一致,详见「控制台 → 提供商」。
导出与恢复备份文件
astra provider export # 写 ./astra-providers-<日期>.json,不含 API Key
astra provider export --out ~/backup/astra.json --force
astra provider export --id < i d > --id < i d > # 只导出指定的提供商
echo 'my passphrase' | astra provider export --passphrase-stdin # 用口令加密密钥(也可设环境变量 ASTRA_BACKUP_PASSPHRASE)
astra provider export --include-keys # 明文密钥,只能在本机操作
astra provider import-file astra-providers.json # 只预览,不写入
astra provider import-file astra-providers.json --yes # 导入状态为 new 的条目
astra provider import-file astra-providers.json --yes --only 0 --only 3 # 只导入预览里指定的行号
默认不含密钥 ;口令和明文密钥都不能写在命令行参数里:口令来自 stdin(终端里是隐藏输入)或 ASTRA_BACKUP_PASSPHRASE,--include-keys 与口令不能同时用;
输出文件以仅所有者可读写(0600)创建,已存在时必须加 --force 才会覆盖;
预览只显示遮掩后的密钥;口令加密的文件导入时同样从 stdin 或环境变量取口令;
文件内容、去重规则和不包含的内容与控制台的「备份与恢复」一致,详见「控制台 → 提供商」。
离线还原:restore-all
astra restore-all
astra restore-all --purge # 同时把 Astra 残留在客户端配置里的条目整个删掉
这是唯一不需要服务在运行 的管理命令:它直接读取 ~/.astra 里记录的接管状态,把每个被接管客户端的配置恢复为启用前的样子。典型场景:
卸载前确保客户端恢复原状(astra uninstall 内部就是先做这件事);
服务无法启动、控制台打不开时的兜底手段。
--purge 不可逆 不加 --purge 时,Astra 写入的配置项会恢复为原值;加了之后连 Astra 的条目痕迹一起清掉。
两者的「首次修改前备份」都仍保留在 ~/.astra/backups/client-configs/。