Skip to content

1-GettingStarted.md

Latest commit

 

History

History
167 lines (110 loc) · 4.48 KB

1-GettingStarted.md

File metadata and controls

167 lines (110 loc) · 4.48 KB
Raw

Getting Started(中文) | Authentication →

Getting Started

This guide explains how to install ve, put it on your PATH, and make a minimal API call.

Requirements

  • Go 1.18 or later is required only when building from source. Prebuilt Release and npm installations do not require Go.
  • Starting from v1.0.20, the command prefix changed from volcengine-cli to ve. Earlier versions are not affected. After upgrading to v1.0.20 or later, update scripts that still call volcengine-cli.
  • Starting from v1.1.3, ve can install and manage Skills (the ve skills commands, and the automatic core Skill installation performed by the npm package). Versions earlier than v1.1.3 do not support Skills, so upgrade first if you need them.

Install

Install with npm

The CLI is published as the npm package @volcengine/cli. If Node.js >= 14 is available, install it globally:

npm install -g @volcengine/cli

The package provides the ve command:

ve version
ve --help

Starting from v1.1.3, installing or upgrading the CLI with npm also installs the core Volcengine Skills; versions earlier than v1.1.3 install no Skills. A Skill installation failure does not fail the CLI installation, and VOLCENGINE_CLI_SKIP_SKILLS=1 skips Skill installation temporarily. After installing, manage the core Skills with ve skills install, ve skills update, and ve skills uninstall (also v1.1.3 or later).

To upgrade an npm install, keep package metadata consistent by upgrading through npm:

npm install -g @volcengine/cli@latest

ve upgrade detects npm installs and runs the same npm install -g command for you (it never replaces the binary in place). If the delegated npm command fails, it prints the manual command above so you can fix permissions or network issues and retry.

For Release binaries or source builds (standalone):

ve upgrade
ve upgrade --yes
ve upgrade --version 1.0.49

Download from Release

  1. Open https://github.com/volcengine/volcengine-cli/releases.
  2. Download the archive for your OS and architecture.
  3. Extract it to get ve, or ve.exe on Windows.

Build from Source

The repository provides build.sh. It can auto-detect the current OS and architecture, or build for an explicit target.

# Build for the current machine
sh build.sh

# Specify OS; architecture is still auto-detected
sh build.sh darwin
sh build.sh linux
sh build.sh windows

# Cross-compile with an explicit architecture: amd64 / arm64 / 386 / arm
sh build.sh linux amd64

# Show help
sh build.sh -h

The output binary is ve, or ve.exe on Windows.

Configure PATH

When installed globally with npm, npm places ve in the global bin directory. If the command is unavailable, check whether npm's global bin directory is in PATH:

npm bin -g

When using Release or a source build, make sure the directory containing ve is in your PATH. A common setup is:

sudo cp ve /usr/local/bin

Verify the command:

ve version
ve --help

If /usr/local/bin is not in $PATH, configure PATH for your shell.

Minimal Configuration

The most direct setup is an AK/SK profile:

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

You can also skip the config file and use environment variables:

export VOLCENGINE_ACCESS_KEY=AK
export VOLCENGINE_SECRET_KEY=SK
export VOLCENGINE_REGION=cn-beijing

See Authentication for more credential modes.

First API Call

List supported services:

ve --help

List actions under a service:

ve ecs --help

Show action parameters:

ve ecs DescribeRegions --help

Call an API:

ve sts GetCallerIdentity

Select a response field and print it as plain text:

ve sts GetCallerIdentity --query 'Result.AccountId' --output text

See Filtering and Output Formats for the supported formats and query safety rules.

Override region for one invocation:

ve sts GetCallerIdentity --region cn-beijing

--region is a public CLI system flag and is placed after the action. If the action exposes an exact case-sensitive business parameter with the same name, the double-dash form is parsed as the business parameter. See Usage for more examples.

Getting Started(中文) | Authentication →