gogcligog auth tokens import命令详解把刷新令牌安全导入系统钥匙串【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog auth tokens import是 gogcliGoogle Workspace in your terminal用于把**包含 OAuth 刷新令牌refresh token的 JSON 文件导入系统钥匙串keyring**的命令。它通常与gog auth tokens export配对使用实现跨机器迁移账号、备份恢复或将令牌文件批量注入 gogcli 的凭据库。读完本文你将掌握该命令的完整用法、JSON 文件格式规范、校验规则、client 解析逻辑以及它背后的源码实现与测试验证方式。命令总览gog auth tokens import属于gog auth tokens子命令族gog-auth-tokens.md同族还包括gog auth tokens list— 列出已存储的令牌仅键名gog auth tokens delete— 删除一个已存储的刷新令牌gog auth tokens export— 把刷新令牌导出到文件含机密其基本用法gog-auth-tokens-import.mdgog auth tokens import inPathinPath是必选位置参数指向包含令牌信息的 JSON 文件路径传入-时则从标准输入读取。命令成功后在标准错误输出一行提示Imported refresh token into keyring表示令牌已写入系统钥匙串。输入文件格式与 export 完全互通的 JSON 结构import 命令读取的 JSON 结构与gog auth tokens export导出的文件结构完全一致因此一条命令导出的文件可以直接用另一条命令原样导回export 与 import 共用同一份结构定义见 internal/cmd/auth_tokens.go 与 internal/cmd/auth_tokens.go。完整字段如下字段类型是否必填说明emailstring必填账号邮箱导入时会做 trim 处理为空则报错refresh_tokenstring必填OAuth 刷新令牌为空则报错subjectstring可选模拟用户service account 场景下的域内用户clientstring可选OAuth client 名称用于选择凭据与令牌桶services[]string可选该令牌授权的服务列表scopes[]string可选OAuth scope 列表created_atstring可选令牌创建时间须为 RFC3339 格式否则报错access_tokenstring可选随附的访问令牌有效约 1 小时access_token_expires_atstring可选访问令牌过期时间须为 RFC3339 格式一个最小可用的导入文件示例{ email: meexample.com, refresh_token: 1//0xxxxxxxxxxxxxxxxxxxxxxxxx }与gog auth tokens export生成的完整示例导出自 internal/cmd/auth_tokens.go 的export结构字段顺序与 JSON 标签保持一致{ email: meexample.com, subject: , client: gog, services: [gmail, calendar], scopes: [https://www.googleapis.com/auth/gmail.modify], created_at: 2025-01-01T00:00:00Z, refresh_token: 1//0xxxxxxxxxxxxxxxxxxxxxxxxx, access_token: , access_token_expires_at: }注意导入时created_at与access_token_expires_at两个时间字段通过time.Parse(time.RFC3339, ...)解析任何非 RFC3339 的值例如bad都会直接导致导入失败。从标准输入读取inPath传入-时命令从 stdin 读取完整 JSON 内容适用于管道场景cat token.json | gog auth tokens import -该路径在源码中通过io.ReadAll(stdinReader(ctx))实现internal/cmd/auth_tokens.go并有对应的 stdin 导入测试用例见下文测试章节。client 解析逻辑flag 优先文件字段兜底导入文件中的client字段并不是必填项。当文件未指定 client 时命令通过resolveClientForEmailWithContext结合全局--clientflag 与已存储凭据决定最终 client若全局 flag 显式指定了--client即上下文中的ClientOverride优先使用该值否则回退到 JSON 文件中的client字段都没有时交由解析函数根据邮箱与已配置凭据推导默认值通常为默认 client 名测试与配置中可见config.DefaultClientName。对应逻辑位于 internal/cmd/auth_tokens.go。这意味着同一个邮箱可以在不同 client 下各自保存一份令牌——测试 auth_tokens_more_test.go 验证了compose、inbox、ro、rw四个 client 下同一邮箱互不覆盖。校验规则与错误处理import 在写入钥匙串之前执行严格的前置校验全部校验失败都以 usage 类错误exit code 2返回校验点失败消息来自源码JSON 无法解析invalid token JSON: erremail为空missing email in token filerefresh_token为空missing refresh_token in token filecreated_at非 RFC3339invalid created_at val (expected RFC3339)access_token_expires_at非 RFC3339invalid access_token_expires_at val (expected RFC3339)文件不存在/不可读读取错误直接返回校验顺序在源码中非常清晰internal/cmd/auth_tokens.go先反序列化 JSON再依次校验 email、refresh_token最后解析两个时间字段。注意时间字段即使传入--dry-run也会先被校验测试用例对此有专门断言见下文。全局 Flags 速查gog auth tokens import不定义专属 flag但继承全部全局 flag见 gog-auth-tokens-import.md 的 Flags 表Flag类型默认作用--access-tokenstring直接使用提供的访问令牌绕过已存储刷新令牌令牌约 1 小时过期-a/--account/--acctstring账号邮箱、别名或 auto用于需认证的 Google API 命令--clientstringOAuth client 名称选择已存凭据 令牌桶--colorstringauto颜色输出auto|always|never--disable-commandsstring禁用的命令列表逗号分隔支持点路径-n/--dry-run/--dryrun/--noop/--previewbool不实际改动仅打印计划执行的动作并成功退出--enable-commandsstring启用的命令前缀列表逗号分隔支持点路径可收窄 CLI--enable-commands-exactstring精确启用的命令列表点路径父命令不会连带启用子命令-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全-h/--helpkong.helpFlag显示上下文相关帮助--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse向 stdout 输出 JSON适合脚本化--no-input/--non-interactive/--noninteractivebool永不提示失败即退出适合 CI-p/--plain/--tsvboolfalse向 stdout 输出稳定可解析文本TSV无颜色--quota-projectstring用于计费 API 用量的 Google Cloud 项目以X-Goog-User-Project头发送部分 API 在--access-token/ADC 下必须--readonlyboolfalse运行时阻止变更类 API 请求auth add也只申请只读 scope--results-onlyboolJSON 模式下只输出主结果丢弃 nextPageToken 等信封字段--select/--pick/--projectstringJSON 模式下选择逗号分隔字段尽力而为支持点路径-v/--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中为外部抓取的文本字段包裹不可信内容标记输出格式默认文本模式输出三行 TSV 风格结果stdoutimported\ttrue、email\t邮箱、client\tclient加-j/--json时输出 JSON 对象{imported: true, email: ..., client: ...}提示信息Imported refresh token into keyring写入stderrinternal/cmd/auth_tokens.go避免污染 stdout 的机器可读输出。实操场景迁移、备份与 CI场景一跨机器迁移账号在一台已登录的机器上导出再到新机器导入# 机器 A导出令牌文件 gog auth tokens export meexample.com --out token.json --overwrite # 机器 B导入令牌 gog auth tokens import token.json gog auth list # 确认账号已可用导出命令写入文件时使用0o600文件权限、0o700目录权限internal/cmd/auth_tokens.go导入端则复用同一 JSON 结构确保来回可迁移。测试 auth_tokens_more_test.go 的TestAuthTokensExportImport_JSON完整演示了「导出到临时目录 → 读回校验refresh_token→ 导入到全新 store → 再取回比对」的往返闭环。场景二dry-run 预演导入属于写操作正式执行前可用-n预览gog auth tokens import token.json -ndry-run 会把将要写入的信息email、client、subject、services、scopes、created_at、refresh_token 是否提供、access_token 相关字段打印出来而不落盘internal/cmd/auth_tokens.go。端到端测试 dryrun_e2e_test.go 将auth.tokens.import列为受支持的 dry-run 操作之一。场景三CI/脚本中安全导入令牌文件本身即机密建议结合--no-input与文件权限控制gog auth tokens import /path/to/token.json --no-input -j--no-input保证在需要交互确认时直接失败而不是挂起-j便于脚本解析imported/email/client字段。源码实现要点命令注册AuthTokensCmd在 internal/cmd/auth_tokens.go 中以name:import注册AuthTokensImportCmdhelp 文案即「Import a refresh token file into keyring (contains secrets)」。结构定义AuthTokensImportCmd仅含一个位置参数InPatharg: name:inPath支持-表示 stdin见 internal/cmd/auth_tokens.go。密钥落点导入最终调用store.SetToken(client, email, secrets.Token{...})底层是KeyringStore基于github.com/99designs/keyring令牌以client:email为键存储键生成见 internal/secrets/token.go 的TokenKey写入前还会调用ensureKeychainAccessIfNeeded确认钥匙串可达internal/cmd/auth_tokens.go。落库前补默认值若导入文件未携带created_atKeyringStore.setTokenNoLock会自动补为当前 UTC 时间internal/secrets/token.goemail会做 normalize 处理refresh_token为空同样被拒绝internal/secrets/token.go。Token 模型secrets.Token中RefreshToken、AccessToken、AccessTokenExpiresAt三个字段 JSON 序列化时被显式排除json:-见 internal/secrets/token.go避免任何日志/序列化路径意外泄露令牌明文。测试与质量保障仓库为 import 命令提供了多层测试证据往返一致性auth_tokens_more_test.go 验证 export 产物能被 import 完整还原异常路径全覆盖auth_validation_more_test.go 的TestAuthTokensImport_ErrorsAndStdin覆盖了不存在的文件路径、非法 JSON、缺失 email、非法created_at含 dry-run 下同样报错、非法access_token_expires_at、以及 stdin 导入成功路径dry-run 集成dryrun_e2e_test.go 把gog auth tokens import tokenPath注册进 dry-run 端到端清单操作名auth.tokens.import。安全注意事项令牌文件即机密refresh_token是长期有效的凭据导出文件务必妥善保管、用后即删export 命令本身也会在 stderr 输出警告WARNING: exported file contains OAuth tokens (keep it safe and delete it when done)见 internal/cmd/auth_tokens.go。文件权限建议沿用 export 的0o600权限约定导入时避免从不可信来源读取令牌文件。最小暴露--json/--plain输出仅包含 imported/email/client 元数据不会回显令牌本身。配合只读策略在受管控环境可结合--readonly、--enable-commands等全局安全 flag 限制命令面相关策略可参考 safety-profiles/agent-safe.yaml 等安全配置。关联文档与延伸阅读父命令gog auth tokens配套导出gog auth tokens export配套删除/列举gog auth tokens delete、gog auth tokens list命令总索引Command index账号管理入口gog auth manage【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考