Configuration

Interactive setup

1. Start the login wizard:

   redmine auth login

2. Provide your Redmine server URL and authentication method (API key or username/password).

3. Optionally set a default project — it is prepopulated in project-scoped commands.

4. The wizard writes a profile to ~/.redmine-cli.yaml. You are ready to go.

Multiple profiles

You can authenticate against as many Redmine instances as you like. Each redmine auth login creates a named profile.

Add

redmine auth login             # second instance
redmine auth login --name work # with an explicit name

Switch

redmine auth list    # see all profiles
redmine auth switch  # interactive picker

Use once

redmine --profile work issues list

Status

redmine auth status

Config file

• Directory~/

  • .redmine-cli.yaml active profile + all profile data
  • Directory.local/bin/

    • redmine binary (install script target)

~/.redmine-cli.yaml

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

Secrets on disk

The config file stores API keys in plaintext. Keep it 0600 and out of dotfile repositories. Use environment variables in CI.

System keyring (optional)

You can keep the API key (or password) out of the config file and in your operating system keyring instead. It is fully opt-in and backward compatible: existing plaintext profiles keep working unchanged.

1. Opt in during login. The wizard asks whether to use the keyring when a usable backend is detected on a TTY. For scripted logins use the flag:

   redmine auth login --keyring

2. The profile records credential_store: keyring and the secret is written to the keyring, not the file. On the next run the secret is read back from the keyring automatically.

Logging in again for a profile that already uses the keyring keeps the keyring by default; it never silently falls back to the plaintext file. Pass --keyring=false to explicitly switch a profile back to plaintext storage.

Resolution order is CLI flag, then environment variable, then keyring, then the plaintext file field. Environment variables and flags are resolved before the keyring is ever consulted.

CI and headless environments

Keep using environment variables (REDMINE_API_KEY, REDMINE_PASSWORD) in CI. Set REDMINE_NO_KEYRING=1 to hard-disable all keyring reads and writes on runners that have no usable keyring, so nothing ever stalls on a keyring prompt.

Environment variables

CI friendly

Every setting can be overridden with a REDMINE_-prefixed variable:

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

# opt out of the startup update check
export REDMINE_NO_UPDATE_CHECK=1

# refuse all requests that modify data (read-only mode)
export REDMINE_READ_ONLY=1

# hard-disable the optional system keyring
export REDMINE_NO_KEYRING=1

See Self-Update for details on the update check.

Global flags

Flags take precedence over config values and environment variables.

Flag	Description
-s, --server	Redmine server URL
-k, --api-key	API key for authentication
--profile	Use a specific auth profile
--config	Config file path (default ~/.redmine-cli.yaml)
--no-color	Disable colored output
--read-only	Refuse all requests that modify data on the server
-v, --verbose	Enable debug logging

Read-only mode

Point the CLI at a production Redmine without any risk of changing data. When enabled, every request that would modify the server is refused before it is sent; all listing, viewing, and searching commands keep working.

Enable it in any of three ways (precedence: flag > environment variable > config):

redmine --read-only issues list   # single invocation
export REDMINE_READ_ONLY=1        # whole shell session

~/.redmine-cli.yaml

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

Pass --read-only=false to override the environment variable or a read_only: true profile for a single invocation.

MCP server

The MCP server has its own gate: mutating tools are only registered when --enable-writes is passed (see AI agents). A profile with read_only: true additionally blocks writes at the HTTP layer, even when --enable-writes is set.

Inspect current config

redmine config

Prints the active profile, server, auth method, default project, output format, and read-only state.

Next

Quick StartFirst real commands: issues, time, search.

Auth commandsFull reference for the auth subcommand family.