authsome

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authsome CLI Skill

Authsome CLI 技能

Manage the credential lifecycle for tools and applications using the

authsome

CLI.

Agent Flow: Every credential request follows three phases in order: SEARCH → LOGIN → USE

使用

authsome

CLI管理工具和应用的凭证生命周期。

代理流程： 每个凭证请求依次遵循三个阶段：搜索 → 登录 → 使用

Prerequisites

前提条件

Before running any

authsome

command, determine how to invoke it:

uvx
(preferred) —
```
uvx authsome <cmd>
```
. No install needed.
pipx
—
```
pipx run authsome <cmd>
```
.
Installed in PATH —
```
authsome <cmd>
```
.
Not found — inform the user. Recommend
```
pip install uv
```
then
```
uvx authsome
```
.

Detection snippet (run once per session):

bash

if command -v uvx &>/dev/null; then
  AUTHSOME="uvx authsome"
elif command -v pipx &>/dev/null; then
  AUTHSOME="pipx run authsome"
elif command -v authsome &>/dev/null; then
  AUTHSOME="authsome"
else
  echo "authsome not found — please install it"
fi

Ensure authsome is initialized before any operation:

bash

$AUTHSOME init

运行任何

authsome

命令之前，先确定调用方式：

uvx
（推荐） —
```
uvx authsome <cmd>
```
。无需安装。
pipx
—
```
pipx run authsome <cmd>
```
。
已安装在PATH中 —
```
authsome <cmd>
```
。
未找到 — 告知用户。推荐先执行
```
pip install uv
```
，再使用
```
uvx authsome
```
。

检测代码片段（每个会话运行一次）：

bash

if command -v uvx &>/dev/null; then
  AUTHSOME="uvx authsome"
elif command -v pipx &>/dev/null; then
  AUTHSOME="pipx run authsome"
elif command -v authsome &>/dev/null; then
  AUTHSOME="authsome"
else
  echo "authsome not found — please install it"
fi

确保在执行任何操作前初始化authsome：

bash

$AUTHSOME init

Phase 1 — SEARCH

阶段1 — 搜索

Goal: Find the provider and check for existing connections.

bash

$AUTHSOME list --json

This returns

bundled

and

custom

provider arrays, each with

name

auth_type

, and

connections

Decision:

Provider found with a connected connection → Ask the user which connection to use (or if they want a new one). If using an existing connection, skip to Phase 3 — USE.
Provider found, no connections → Proceed to Phase 2 — LOGIN.
Provider NOT found → You must create and register a custom provider. Read REGISTER_PROVIDER.md for the full guide, then return here for Phase 2.

目标： 找到提供商并检查现有连接。

bash

$AUTHSOME list --json

此命令返回

bundled

和

custom

提供商数组，每个数组包含

name

、

auth_type

和

connections

字段。

决策：

找到提供商且已有连接 → 询问用户使用哪个连接（或是否需要新建）。如果使用现有连接，直接跳至阶段3 — 使用。
找到提供商但无连接 → 继续阶段2 — 登录。
未找到提供商 → 必须创建并注册自定义提供商。阅读REGISTER_PROVIDER.md获取完整指南，然后返回此处进行阶段2操作。

Phase 2 — LOGIN

阶段2 — 登录

Goal: Authenticate and store credentials.

目标： 完成认证并存储凭证。

Step 2.1: Determine the auth flow

步骤2.1：确定认证流程

If the provider supports multiple OAuth2 flows, choose one:

supports_dcr: true
→ Use
dcr_pkce
. This is the path of least resistance — no pre-registered
```
client_id
```
needed.
Multiple flows available (no DCR) → Ask the user: PKCE (browser) vs Device Code (headless).
Only one flow → Use the provider's default.
API key provider → Flow is already determined (
```
api_key
```
).

Use

$AUTHSOME inspect <provider> --json

to check

oauth.supports_dcr

oauth.supports_device_flow

, and the default

flow

如果提供商支持多种OAuth2流程，选择其中一种：

supports_dcr: true
→ 使用
dcr_pkce
。这是最简便的方式——无需预先注册
```
client_id
```
。
支持多种流程（无DCR） → 询问用户：选择PKCE（浏览器）还是设备码（无头模式）。
仅支持一种流程 → 使用提供商的默认流程。
API密钥提供商 → 流程已确定（
```
api_key
```
）。

使用

$AUTHSOME inspect <provider> --json

命令查看

oauth.supports_dcr

、

oauth.supports_device_flow

以及默认

flow

。

Step 2.2: Choose a connection name

步骤2.2：选择连接名称

If the user already has a

"default"

connection for this provider, ask for a name (e.g.,

work

personal

). Otherwise use

"default"

如果用户已为此提供商创建了

"default"

连接，询问用户新连接的名称（例如

work

、

personal

）。否则使用

"default"

。

Step 2.3: Run login

步骤2.3：执行登录

bash

$AUTHSOME login <provider> [--connection <name>] [--flow <flow_type>] [--scopes <scope1,scope2>] [--client-id <id>] [--client-secret <secret>] [--api-key <key>]

Note on Credentials:

authsome

stores client IDs and secrets securely in the profile store. If this is the first time logging in with a specific provider that doesn't use Dynamic Client Registration (DCR), you MUST pass the credentials via flags (

--client-id

and

--client-secret

). They will be securely saved and reused for subsequent logins for that provider.

Note on Redirect URIs: If the provider requires you to register an OAuth App manually (e.g., standard PKCE flow without DCR), make sure to configure the callback/redirect URI in the provider's developer console to exactly

http://127.0.0.1:7999/callback

Examples:

bash

undefined

bash

$AUTHSOME login <provider> [--connection <name>] [--flow <flow_type>] [--scopes <scope1,scope2>] [--client-id <id>] [--client-secret <secret>] [--api-key <key>]

凭证说明：

authsome

会将客户端ID和密钥安全存储在配置文件存储中。如果是首次登录某个不支持动态客户端注册（DCR）的提供商，必须通过标志（

--client-id

和

--client-secret

）传递凭证。这些凭证会被安全保存，并在后续该提供商的登录操作中重复使用。

重定向URI说明： 如果提供商要求手动注册OAuth应用（例如无DCR的标准PKCE流程），请确保在提供商的开发者控制台中将回调/重定向URI配置为完全匹配

http://127.0.0.1:7999/callback

。

示例：

bash

undefined

Default flow (if credentials are saved or provider supports DCR)

默认流程（如果凭证已保存或提供商支持DCR）

$AUTHSOME login github

First-time login for provider requiring client credentials

首次登录需要客户端凭证的提供商

$AUTHSOME login github --client-id "my_client_id" --client-secret "my_client_secret"

Override flow to device code

覆盖流程为设备码

$AUTHSOME login github --flow device_code --client-id "my_client_id"

API key provider (bypass interactive prompt by passing key)

API密钥提供商（通过传递密钥跳过交互式提示）

$AUTHSOME login openai --api-key "sk-..."

undefined

$AUTHSOME login openai --api-key "sk-..."

undefined

Step 2.4: Verify

步骤2.4：验证

bash

$AUTHSOME get <provider> --json

Confirm

status

"connected"

bash

$AUTHSOME get <provider> --json

确认

status

为

"connected"

。

Phase 3 — USE

阶段3 — 使用

Goal: Export credentials so the agent can make authenticated tool calls.

目标： 导出凭证以便代理可以进行已认证的工具调用。

Option A: Export to current shell (recommended)

选项A：导出到当前shell（推荐）

bash

eval "$($AUTHSOME export <provider> --format shell)"

Credentials become environment variables (e.g.,

GITHUB_ACCESS_TOKEN

OPENAI_API_KEY

) as defined in the provider's

export.env

mapping.

bash

eval "$($AUTHSOME export <provider> --format shell)"

凭证会变为环境变量（例如

GITHUB_ACCESS_TOKEN

、

OPENAI_API_KEY

），具体对应关系由提供商的

export.env

映射定义。

Option B: Run a command with injected credentials

选项B：运行注入凭证的命令

bash

$AUTHSOME run --provider github -- curl -H "Authorization: Bearer $GITHUB_ACCESS_TOKEN" https://api.github.com/user

Multiple providers:

bash

$AUTHSOME run --provider github --provider openai -- python my_script.py

bash

$AUTHSOME run --provider github -- curl -H "Authorization: Bearer $GITHUB_ACCESS_TOKEN" https://api.github.com/user

多个提供商：

bash

$AUTHSOME run --provider github --provider openai -- python my_script.py

Option C: Get a single field

选项C：获取单个字段

bash

TOKEN=$($AUTHSOME get <provider> --field access_token --show-secret)

bash

TOKEN=$($AUTHSOME get <provider> --field access_token --show-secret)

Additional Resources

额外资源

Topic	File
Creating & registering custom providers	REGISTER_PROVIDER.md
Full CLI command & flag reference	CLI_REFERENCE.md

主题	文件
创建并注册自定义提供商	REGISTER_PROVIDER.md
完整CLI命令及标志参考	CLI_REFERENCE.md

Best Practices

最佳实践

Always use
--json
when parsing CLI output programmatically.
Prefer
authsome run
over exporting secrets — it is more secure and ephemeral.
Never log or echo secrets unless the user explicitly asks.
Re-use existing connections — always check before starting a new login.

编程解析CLI输出时始终使用
--json
。
**优先使用
```
authsome run
```
**而非导出密钥——这种方式更安全且具有临时性。
除非用户明确要求，否则切勿记录或回显密钥。
重用现有连接——开始新登录前始终检查现有连接。