gogcligog auth add完全指南在终端授权 Google 账户并安全存储刷新令牌【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog auth add是 gogcliGoogle Workspace in your terminal中负责 OAuth 授权的核心命令它引导用户在浏览器中完成 Google 账户或 Google Workspace 账户授权获取并安全存储刷新令牌refresh token为后续所有 Gmail、Drive、Calendar、Sheets 等命令调用提供身份基础。读完本篇你将掌握该命令的完整参数体系、浏览器/无浏览器两种授权流程、服务与 scope 的精细控制以及授权后身份校验与令牌存储的底层实现原理。命令定位与基础用法gog auth add属于 gog auth 子命令族职责是“授权一个 Google Account 或 Google Workspace 账户并存储刷新令牌”。该文档由gog schema --json自动生成执行make docs-commands可重新生成。基础用法gog auth add email [flags]其中email是必需的位置参数。源码中它被定义为AuthAddCmd的Email字段internal/cmd/auth_add.go其帮助文本明确指出必须是 Google Account 或 Google Workspace 邮箱普通非 Google 邮箱无法完成授权。执行时会先输出一条提示googleAccountAuthorizationHint若同意授权失败应显式指定--services重试并在重新授权时保留已有服务。快速上手标准浏览器授权流程在配置好 OAuth 客户端凭证后参见 gog auth credentials 与 gog auth setup最简单的一次授权只需gog auth add youexample.com默认行为源码Run方法流程见 internal/cmd/auth_add.go解析账户对应的 OAuth 客户端authclient.ResolveClientWithOverride解析--services默认加载全部默认用户服务user预设计算 OAuth scope 列表googleauth.ScopesForManageWithOptionsinternal/googleauth/service.go启动本地回调监听打开浏览器完成授权用刷新令牌回调用户信息fetchAuthIdentity校验授权邮箱与命令行传入邮箱一致将令牌写入密钥库/加密存储secrets.Store.SetToken。授权成功后输出账户邮箱、已授权服务与客户端名。测试 internal/cmd/auth_add_test.go 中的TestAuthAddCmd_EmailMismatch验证了邮箱不匹配时命令直接报错拒绝存储。Flags 完整参考以下表格完整继承自官方命令文档docs/commands/gog-auth-add.md其中--access-token等全局 Flags 用于所有 gogcli 命令而--manual、--remote、--services、--drive-scope、--gmail-scope等为授权流程专属参数Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的刷新令牌令牌约 1 小时后过期-a--account--acctstring账户邮箱、别名或 auto用于已认证的 Google API 命令--auth-urlstring浏览器回调后的重定向 URL手动流程--remote --step 2必填--clientstringOAuth 客户端名选择已存储的凭证与令牌桶--colorstringauto彩色输出auto|always|never--disable-commandsstring逗号分隔的禁用命令列表支持点路径--drive-scopestringfullDrive scope 模式full|readonly|file-n--dry-run--dryrun--noop--previewbool不实际改动打印计划动作后成功退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 范围--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不自动启用子命令--extra-scopesstring逗号分隔的额外 OAuth scope URI 列表追加在服务 scope 之后-y--force--assume-yes--yesbool跳过破坏性命令的确认--force-consentbool强制显示同意页以获得刷新令牌--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全--gmail-scopestringfullGmail scope 模式full|readonly|send|read-send-h--helpkong.helpFlag显示上下文相关帮助--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于 GOG_HOME-j--json--machineboolfalse输出 JSON 到 stdout适合脚本化--listen-addrstringOAuth 回调监听地址例如 0.0.0.0 或 0.0.0.0:8080--manualbool无浏览器授权流程粘贴重定向 URL--no-input--non-interactive--noninteractivebool从不提示失败则直接报错适用于 CI-p--plain--tsvboolfalse输出稳定可解析的文本TSV无颜色--quota-projectstring用于 API 计费的 Google Cloud 项目发送 X-Goog-User-Project 头部分 API 配合--access-token或 ADC 时需要--readonlyboolfalse运行时阻止变更类 API 请求auth add同时只请求只读 OAuth scope--redirect-hoststring浏览器流程 OAuth 回调主机名拼装为https://{host}/oauth2/callback--redirect-uristring覆盖手动/远程流程的 OAuth 重定向 URI例如 https://host.example/oauth2/callback--remotebool远程/服务器友好手动流程先打印 URL再交换 code--results-onlyboolJSON 模式下只输出主结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下按逗号分隔选择字段尽力而为支持点路径--servicesstringuser授权服务user|all-user 或逗号分隔的 gmail,calendar,chat,classroom,drive,driveactivity,drivelabels,docs,slides,contacts,tasks,sheets,people,forms,sites,meet,appscript,analytics,searchconsole,ads,youtube,photos显式 opt-inadsense, photospickerall 表示全部默认用户 OAuth 服务。仅 Workspace 服务账号的服务admin, groups, keep--stepint远程授权步骤1打印 URL2交换 code--timeouttime.Duration授权超时手动流程默认 5 分钟-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中给外部获取的文本字段包裹 untrusted 内容标记无浏览器场景manual 与 remote 两步流程对于无图形界面的服务器或 SSH 环境gog auth add提供两种无浏览器授权方式相关标志定义与校验逻辑见 internal/cmd/auth_add.go。--manual粘贴回调 URLgog auth add youexample.com --manual命令打印授权 URL你在任何有浏览器的设备上打开并完成授权再把浏览器重定向地址复制粘贴回终端。--redirect-uri可覆盖默认回调地址--timeout可调整等待时间未指定时手动流程默认 5 分钟。--remote --step远程服务器两段式适合自动化脚本分两次执行# 第一步打印授权 URL不启动回调监听 gog auth add youexample.com --remote --step 1 # 第二步带上浏览器重定向 URL 交换 code gog auth add youexample.com --remote --step 2 --auth-url redirect-url第一步还会输出state_reused提示并回显第二步需要复用的完整命令formatRemoteStep2Instruction会把--redirect-host、--redirect-uri、--services、--readonly、--drive-scope、--gmail-scope、--extra-scopes、--force-consent等参数一并拼进提示。第二步要求--auth-url必填并且强制进行 state 校验源码中--auth-code与--remote互斥见 internal/cmd/auth_add.go--step只允许 1 或 2且必须与--remote同时使用。--redirect-host与--redirect-uri互斥resolvedRedirectURI前者拼接为https://{host}/oauth2/callback后者直接覆盖整个 URI。服务范围与 scope 精细控制--services选择授权服务默认值user覆盖全部默认用户 OAuth 服务也可以按需精确挑选例如gog auth add youexample.com --services gmail,calendar,drive,docs,sheets要点源码 parseAuthServices 与测试 auth_add_test.go 中的TestAuthServicesAdSenseExplicitOptIn、TestAuthAddCmd_KeepRejected支持user/all-user/all预设以及逗号分隔的服务名列表adsense、photospicker必须显式列名 opt-inadmin、groups、keep仅适用于 Workspace 服务账号走gog auth service-account set email --key service-account.json路线直接传给auth add会返回 usage 错误重复项自动去重未选服务时报 “no services selected”。--drive-scope与--gmail-scope--drive-scopefull默认/readonly/file--gmail-scopefull默认/readonly/send/read-send。authScopeModesinternal/cmd/auth_add.go负责组合校验任何非 full 的 Gmail 模式或 readonly/file 的 Drive 模式都会关闭增量授权DisableIncludeGrantedScopes从而在再次授权时重新请求完整 scope 清单。相关测试覆盖了 Gmail 发送类 scope 与 readonly 的冲突TestAuthAddCmd_ReadonlyRejectsGmailSendingScopes。--readonly只读授权--readonly会同时做两件事运行时拦截变更类 API 请求且本次auth add只申请只读 OAuth scope。注意它不能与--drive-scopefilefile 具备写能力或--gmail-scopesend/read-send组合组合时报 usage 错误见authScopeModes与测试TestAuthAddCmd_ReadonlyWithDriveScopeFileRejected。--extra-scopes与--force-consent--extra-scopes以逗号分隔追加自定义 scope URI追加在所有服务 scope 之后parseExtraScopesCSV会做 trim 与去空处理--force-consent强制显示同意页确保 Google 返回刷新令牌对已授权过的账户很有用可强制刷新授权状态。源码级原理身份校验、令牌存储与邮箱迁移授权成功后的处理链internal/cmd/auth_add.go值得关注身份校验用刷新令牌回调用户信息fetchAuthIdentity超时 15 秒将返回的授权邮箱与命令行传入邮箱做规范化比较normalizeEmail统一小写去空格。不一致则报错authorized as X, expected Y避免“授权了错误账户还写入存储”。令牌存储openAuthSecretsStore打开密钥库keyring/加密文件--readonly之外的变更类操作前还会先ensureKeychainAccessIfNeeded验证密钥库可访问随后store.SetToken写入Client / Subject / Email / Services / Scopes / RefreshToken。存储失败时报OAuth completed, but saving the refresh token failed: ...明确区分“授权成功但保存失败”。邮箱迁移若FindStoredSubjectIdentityEmail发现旧账户例如大小写或别名变化会自动把旧邮箱引用迁移到新邮箱并删除过期别名输出Migrated auth account from A to B测试TestExecuteAuthAddMigratesRuntimeEmailReferences覆盖。该命令支持--dry-run在任何 OAuth 网络操作前打印计划动作并退出dryRunExit测试TestAuthAddCmd_DryRunSkipsOAuthForEveryFlow验证了 dry-run 对所有流程都不会发起真实 OAuth。输出格式与脚本化配合全局 Flags 可安全地接入脚本-j/--json/--machine输出{stored, email, services, client}结构-p/--plain/--tsv输出emailTAB...、servicesTAB...、clientTAB...的 TSV 行无颜色便于 grep/awk--no-input/--non-interactiveCI 环境下不进入交互提示直接失败。授权后的账户管理链路gog auth add只是整个认证体系的入口后续管理请配合gog auth list列出已存储账户gog auth status查看认证配置与密钥库后端gog auth import非交互式导入刷新令牌如从环境变量/文件/stdin 读取适合无法打开浏览器的机器gog auth remove / gog auth tokens移除或管理刷新令牌gog auth doctor诊断 auth、密钥库与刷新令牌问题gog auth service-accountWorkspace 域范围委托admin/groups/keep 服务需要。完整命令索引见 Command index。合理使用--dry-run先预览授权计划、用--services最小化权限、必要时叠加--readonly与--gmail-no-send即可在保证安全的前提下完成 gogcli 的全部终端自动化场景。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考