auth

contract-cli Auth

This skill guides you on how to use contract-cli 's login and identity switching capabilities in this repository, and stay consistent with the current implementation.

Scope

• Initialize local profile
• with user identity via OAuth authorization code + PKCE login
• with bot identity, enter app_id/app_secret
• View or clear local identity status
• Switch the default business identity
• Troubleshoot config.json and secrets.json local persistence issues

Implementation source

• internal/cli/app.go
• internal/cli/auth_provider.go
• internal/config/store.go
• internal/config/secrets.go

Configuration initialization

Before first use, you must run:

contract-cli config add --env dev

The current implementation only has built-in dev environment, with the default profile named contract-group. This command will:

• Discover well-known metadata
• Save MCP server / resource / OAuth server configuration
• Initialize default_identity as user

identity model

Two identities are maintained under the same profile:

Identity	Command	Local storage	Current implementation
user	contract-cli auth login --as user	profiles.<name>.identities.user.token	OAuth login implemented
bot	contract-cli auth login --as bot	profiles.<name>.identities.bot + secrets.json	Credential entry and tenant_access_token exchange implemented

There is also an additional default identity pointer:

• profiles.<name>.default_identity
• Modified by contract-cli auth use --as user|bot Modify
• auth login --as ... After success, it will also automatically switch to the corresponding identity

Quick flow

user login

contract-cli config add --env dev
contract-cli auth login --as user
contract-cli auth status --as user

Behavior constraints:

• user login automatically registers client_id
• Uses authorization code mode + PKCE
• Will start a local callback service; the callback address comes from the profile's redirect_url
• By default, automatically opens the browser; to only print the link, use --no-open-browser
• After successful login, write identities.user.token

bot login

contract-cli auth login --as bot --app-id "<app_id>" --app-secret "<app_secret>"
contract-cli auth status --as bot

Credentials can also be provided via environment variables:

export CONTRACT_CLI_BOT_APP_ID="<app_id>"
export CONTRACT_CLI_BOT_APP_SECRET="<app_secret>"
contract-cli auth login --as bot

At runtime it is also compatible with the old variable DEMOCLI_BOT_APP_ID / DEMOCLI_BOT_APP_SECRET, but newly added configurations should uniformly use CONTRACT_CLI_*。

Credential priority is fixed as:

• Command-line arguments
• Environment variables
• Locally saved credentials

Behavior constraints:

• bot login will first save app_id/app_secret, then call tenant_access_token/internal to exchange for token
• app_secret is not written to config.json
• After token success, write identities.bot.token
• If token exchange fails, the new credentials will be retained, but the default identity will not be switched to bot
• After successful login, will switch default_identity=bot

Status, logout, and switching

View status

contract-cli auth status --as user
contract-cli auth status --as bot

Rules:

• When --as is not passed,auth status defaults to viewing user
• user shows authorized or unauthorized
• bot shows authorized、expired、configured or unconfigured
• bot status will show Token Endpoint、Token Protocol: tenant_access_token/internal and expiration time (if any)

Logout

contract-cli auth logout --as user
contract-cli auth logout --as bot

Rules:

• logout --as user only clears user.token
• logout --as bot only clears bot.token, retains app_id/app_secret and the corresponding secret
• When --as is not passed,auth logout defaults to handling user

Switch default identity

contract-cli auth use --as user
contract-cli auth use --as bot

Rules:

• This command only modifies default_identity
• does not log in again
• does not verify that the target identity has already obtained a token

Local file

The default path is as follows; if CONTRACT_CLI_CONFIG_DIRis set, it changes to that directory:

• ~/.contract-cli/config.json
• ~/.contract-cli/secrets.json

At runtime it is also compatible with the old DEMOCLI_CONFIG_DIR and the historical default directory ~/.democli, for smoothly reading the existing local login state.

Storage constraints:

• config.json saves profile, identity metadata, and token
• secrets.json only saves the bot's app_secret
• user.token and bot.token are stored separately and are not shared
• Legacy flat OAuth fields are automatically migrated to identities.user

Security rules

• Do not output in plaintext in the terminal or documentation app_secret、access_token、refresh_token
• Do not bot describe bot logout as "deleting credentials"; the current implementation only clears the token and does not delete app_id/app_secret
• Do not let users mistakenly think that default_identity will affect auth status or auth logout 's default target; when these two commands are not passed --as , they still follow user
• When writing or clearing local credentials, first confirm that the operation is on the current profile

Troubleshooting

• user identity is not configured: first run contract-cli config add --env dev
• Browser does not open automatically: use --no-open-browser, and manually visit the output authorization link
• Callback timeout: check whether the port corresponding to redirect_url can be listened on, and increase it if necessary --timeout
• Bot credentials incomplete: complete --app-id/--app-secret or set CONTRACT_CLI_BOT_APP_ID/CONTRACT_CLI_BOT_APP_SECRET
• Bot login prompt is missing bot_token_endpoint: this indicates the profile is too old; rerun contract-cli config add --env dev --name <profile>
• Bot status shows expired: rerun contract-cli auth login --as bot