配置

交互式设置

启动登录向导：
终端窗口
```
redmine auth login
```
提供你的 Redmine 服务器 URL 和身份验证方式（API 密钥或用户名/密码）。
可选：设置默认项目——该项目会在项目范围的命令中自动填充。
向导将配置写入 ~/.redmine-cli.yaml，之后即可开始使用。

多个配置文件

你可以对任意数量的 Redmine 实例进行身份验证。每次执行 redmine auth login 都会创建一个命名配置文件。

redmine auth login             # 第二个实例
redmine auth login --name work # 显式指定名称

redmine auth list    # 查看所有配置文件
redmine auth switch  # 交互式选择器

redmine --profile work issues list

redmine auth status

配置文件

文件夹~/
- .redmine-cli.yaml 活跃配置文件及所有配置数据
- 文件夹.local/bin/
  - redmine 二进制文件（安装脚本目标路径）

active_profile: work
profiles:
  work:
    server: https://redmine.work.com
    auth_method: apikey
    api_key: your-api-key
    default_project: myproject
    output_format: table
  personal:
    server: https://redmine.personal.com
    auth_method: apikey
    api_key: another-key
    output_format: json

系统密钥环（可选）

你可以将 API 密钥（或密码）保存在操作系统的密钥环中，而不是配置文件里。此功能完全需要主动启用，并向后兼容：现有的明文配置文件将继续照常工作。

在登录时启用。当检测到终端上有可用的密钥环后端时，向导会询问是否使用密钥环。对于脚本化登录，请使用以下标志：
终端窗口
```
redmine auth login --keyring
```
该配置文件会记录 credential_store: keyring，密钥被写入密钥环而非文件。下次运行时会自动从密钥环读取该密钥。

对于已使用密钥环的配置文件，再次登录时默认继续使用密钥环，绝不会静默回退到明文文件。如需将配置文件显式切换回明文存储，请传入 --keyring=false。

解析顺序为：命令行标志、环境变量、密钥环，最后才是明文文件中的字段。环境变量和标志始终在访问密钥环之前解析。

环境变量

适用于 CI

所有配置项均可通过以 REDMINE_ 为前缀的环境变量覆盖：

export REDMINE_SERVER=https://redmine.example.com
export REDMINE_API_KEY=your-api-key
export REDMINE_AUTH_METHOD=apikey

# 关闭启动时的更新检查
export REDMINE_NO_UPDATE_CHECK=1

# 拒绝所有修改数据的请求（只读模式）
export REDMINE_READ_ONLY=1

# 彻底禁用可选的系统密钥环
export REDMINE_NO_KEYRING=1

参见自动更新了解更新检查的详细信息。

全局标志

标志优先级高于配置文件值和环境变量。

标志	描述
`-s, --server`	Redmine 服务器 URL
`-k, --api-key`	用于身份验证的 API 密钥
`--profile`	使用指定的身份验证配置文件
`--config`	配置文件路径（默认为 `~/.redmine-cli.yaml`）
`--no-color`	禁用彩色输出
`--read-only`	拒绝所有修改服务器数据的请求
`--header`	额外的 HTTP 请求头，格式为 `"Name: value"`（可重复）
`-v, --verbose`	启用调试日志

只读模式

将 CLI 指向生产环境的 Redmine 而无需担心数据被修改。启用后，任何会修改服务器数据的请求都会在发送前被拒绝；所有列表、查看和搜索命令继续正常工作。

可通过三种方式启用（优先级：标志 > 环境变量 > 配置文件）：

redmine --read-only issues list   # 单次调用
export REDMINE_READ_ONLY=1        # 整个 shell 会话

profiles:
  prod:
    server: https://redmine.example.com
    auth_method: apikey
    api_key: your-api-key
    read_only: true

传入 --read-only=false 可在单次调用中覆盖环境变量或配置文件中的 read_only: true。

自定义 HTTP 请求头

部分服务器位于防火墙或反向代理之后，要求附加请求头，例如类似浏览器的 User-Agent 或访问令牌。可在配置文件的 headers 下按配置文件添加：

profiles:
  work:
    server: https://redmine.work.com
    auth_method: apikey
    api_key: your-api-key
    headers:
      User-Agent: Mozilla/5.0
      X-Proxy-Token: your-proxy-token

单次调用时可传入 --header（可重复），它会覆盖配置文件中同名的请求头：

redmine --header "User-Agent: Mozilla/5.0" issues list

传给 redmine auth login 时，这些请求头会用于连接测试并保存到配置文件中，因此需要它们的服务器在首次登录时即可使用：

redmine auth login --header "User-Agent: Mozilla/5.0"

再次登录时，只要服务器主机不变，配置文件中的请求头会被保留。若将配置文件指向其他服务器，这些请求头会被丢弃，因为它们可能是属于旧服务器的机密信息。如需删除某个请求头，请直接在配置文件中将其删除。

请求头只会发送到配置的服务器，不会发送到其重定向的其他主机。身份验证请求头始终优先。由 HTTP 客户端自行管理的请求头（Host、Content-Type、Content-Length、Transfer-Encoding、Connection、Accept-Encoding）无法配置，空值也会被拒绝。未配置 User-Agent 时，CLI 以 redmine-cli/<version> 标识自己。

查看当前配置

redmine config

输出活跃配置文件、服务器、身份验证方式、默认项目、输出格式、只读状态以及已配置请求头的名称（不显示值）。

下一步

快速开始第一批实用命令：工单、工时记录、搜索。

身份验证命令auth 子命令系列的完整参考。