Skip to content

3-Configuration.md

Latest commit

 

History

History
243 lines (166 loc) · 8.72 KB

3-Configuration.md

File metadata and controls

243 lines (166 loc) · 8.72 KB
Raw

← Authentication | Configuration(中文) | Usage →

Configuration

CLI profiles and SSO sessions are stored in ~/.volcengine/config.json by default. The config file is written with 0600 permissions, and the config directory is created with 0700 permissions.

This document covers profile inspection, switching, updates, and deletion. Credential modes are covered in Authentication.

Config File Structure

The config file contains:

  • current: current default profile name.
  • profiles: profile map.
  • sso-session: SSO session map.
  • enableColor: whether colored JSON output is enabled. See Advanced Usage.

Example:

{
    "current": "prod",
    "profiles": {
        "prod": {
            "name": "prod",
            "mode": "ak",
            "access-key": "AK",
            "secret-key": "SK",
            "region": "cn-beijing"
        }
    },
    "enableColor": false,
    "sso-session": {}
}

Avoid manually editing sensitive fields. Prefer CLI commands.

Show Current Profile

ve configure get

Without --profile, the command shows the current profile:

no profile name specified, show current profile: [prod]

Show a Specific Profile

ve configure get --profile prod

If the profile does not exist, the command prints an empty profile object and does not create it.

List All Profiles

ve configure list

The output starts with current:

*** current profile: prod ***

Then each profile in the config file is printed.

Switch Current Profile

ve configure profile --profile prod

--profile is required. If the profile does not exist, current is not changed and an error is returned.

Switching current affects later service commands that do not specify --profile. For a single invocation, use:

ve ecs DescribeInstances --profile prod

Create or Update a Profile

ve configure set --profile prod --region cn-beijing --access-key AK --secret-key SK

Behavior:

  • --profile is required.
  • If the profile does not exist, it is created with default mode ak.
  • If the profile exists, only non-empty fields provided in this command are updated; omitted fields keep their previous values.
  • --disable-ssl and --use-dual-stack are written only when explicitly provided.
  • Successful create or update switches current to that profile.
  • region is not mandatory during configure set, but API calls must be able to resolve a region.

Update region:

ve configure set --profile prod --region cn-shanghai

Update endpoint:

ve configure set --profile prod --endpoint ecs.cn-beijing.volcengineapi.com

Use the standard endpoint resolver:

ve configure set --profile prod --endpoint-resolver standard

Configure proxy:

ve configure set --profile prod --https-proxy http://127.0.0.1:7890

Enable dual-stack:

ve configure set --profile prod --use-dual-stack

Disable SSL:

ve configure set --profile prod --disable-ssl

Delete a Profile

ve configure delete --profile prod

--profile is required. If the deleted profile is current, the CLI selects one remaining profile as the new current. If no profiles remain, current becomes empty.

Deleting a profile does not delete SSO sessions or the global Console Login cache directory. Console Login cache cleanup is covered in Authentication.

Safety Policy

The safety policy is a local client-side guard for OpenAPI operations issued by ve, including normal calls, --force calls, and MCP call_api. It complements Volcengine IAM and does not replace cloud-side authorization. Delegated ve arkcli and ve tosutil commands are not intercepted because their arguments are forwarded unchanged.

The policy is disabled by default and stored separately in ~/.volcengine/safety-policy.json with 0600 permissions. Enable it and add rules with:

ve configure safety-policy enable
ve configure safety-policy add --pattern '*:Delete*' --action deny
ve configure safety-policy add --pattern '*:Update*' --action confirm
ve configure safety-policy list

Actions:

  • allow: explicitly allow a matching operation. Configure it in the JSON file or through VOLCENGINE_SAFETY_POLICY_RULES; the add command intentionally accepts only protective actions.
  • deny: reject the operation locally without sending an API request.
  • confirm: require explicit approval before sending the request.

Rules use service:action, are matched case-insensitively, support *, and use first-match-wins order. An unmatched operation is allowed. Every spelling of a service is treated as the same service, including versioned commands, underscore-compatible commands, and the SDK service name. For example, cloudtrail:Delete*, cloudtrail20180101:Delete*, and cloud_trail:Delete* are equivalent and apply to ve cloudtrail, ve cloudtrail20180101, and MCP call_api; rds_mysql:* likewise covers ve rdsmysql, ve rdsmysqlv2, and ve rds_mysql_v2. API names are matched as written, with no other spelling conversion.

Patterns must contain exactly one colon, with a non-empty service and action and no internal whitespace. Surrounding whitespace is ignored. For example, use sts:GetCallerIdentity, sts:*, *:GetCallerIdentity, or *:*; API-only names, service-only names, dot/space separators, and a lone * are rejected. Validation checks syntax only, so rules may cover unlisted services and future APIs used with --force.

For rule management, add and remove compare the complete pattern text case-insensitively. add updates the first matching pattern in place, preserving its position; otherwise, it appends a rule. remove deletes all matching patterns and still succeeds if none exist. Wildcards and service aliases are not expanded when locating stored patterns.

{
  "enabled": true,
  "rules": [
    {"pattern": "ecs:Describe*", "action": "allow"},
    {"pattern": "ecs:*", "action": "deny"}
  ]
}

In an interactive terminal, a confirm match prompts for yes. Agents must start each operation without --yes. Only after a confirmation error (no API request sent), briefly explain the target and impact, ask to continue, then end the turn and wait for a new user reply. After approval, internally add --yes or -y for one unchanged retry; do not ask the user to handle the flag. Discard approval after that attempt, even on failure. The next operation starts without approval again. This is agent guidance, not a single-use token enforced by the CLI. Example of the approved retry:

ve ecs UpdateInstance --InstanceId i-xxxxx --yes

--yes skips only confirm; it never bypasses deny. MCP clients use yes: true on the repeated call_api request. See MCP Server.

Environment overrides have higher priority than the file:

Variable Description
VOLCENGINE_SAFETY_POLICY_ENABLED Override enabled (true/false, also Go boolean forms such as 1/0)
VOLCENGINE_SAFETY_POLICY_RULES Replace the file rules with comma-separated pattern=action entries
VOLCENGINE_SAFETY_SKIP_CONFIRM Treat confirmation as approved for this process (1, true, yes, or on)

Examples:

export VOLCENGINE_SAFETY_POLICY_ENABLED=true
export VOLCENGINE_SAFETY_POLICY_RULES='ecs:Describe*=allow,*:Delete*=deny,*:Update*=confirm'

Invalid policy files and invalid environment overrides fail closed: the CLI reports the configuration error and does not send the API request. Pattern syntax is validated when adding, saving, or loading rules and when parsing environment overrides. If an existing policy file contains malformed patterns, correct them directly in ~/.volcengine/safety-policy.json before using policy management or API commands again.

Selection Examples

Switch Between Environments

ve configure set --profile dev --region cn-beijing --access-key DEV_AK --secret-key DEV_SK
ve configure set --profile prod --region cn-beijing --access-key PROD_AK --secret-key PROD_SK

ve configure profile --profile dev
ve ecs DescribeInstances

ve configure profile --profile prod
ve ecs DescribeInstances

Override Profile for One Call

ve configure profile --profile dev
ve ecs DescribeInstances --profile prod

This call uses prod only for this invocation and does not modify current.

Override Region and Endpoint for One Call

ve ecs DescribeInstances --region cn-shanghai
ve sts GetCallerIdentity --region cn-beijing --endpoint sts.volcengineapi.com

← Authentication | Configuration(中文) | Usage →