Docs

Torch Log Service

CLI reference

Install and use TLS CLI

This section describes how to install and use the CLI tool provided by Volcengine TLS.

Prerequisites

You have obtained the Volcengine account AK (Access Key ID) and SK (Secret Access Key). For details, see Access Key (Key) Management. Taking AK/SK certifications as examples, Authentication introduces more authentication methods.

You have obtained the Region ID and service address (Endpoint) information for the TLS region.

Region: For example, cn-beijing

Endpoint: For example, https://tls-cn-beijing.volces.com

Quick start (AI Agent)

To install using volclog-human, see the "Human-being" section of Quick start with CLI for details.

This step uses the recommended main path for Agent, CI, and automation to quickly install and use volclog.

Install and verify volclog.

Install volclog.

Binary (recommended)
NPM

VOLCLOG_BASE_URL=https://github.com/volcengine-tls/ve-tls-cli/releases/latest/download \
bash scripts/install-binary.sh

Verify successful installation.

volclog --version

Configure credentials.

Create a local profile or inject one-time credentials, then verify with doctor.

volclog configure set \
--profile default \
--ak <ak> \
--sk <sk> \
--region cn-beijing \
--endpoint https://tls-cn-beijing.volces.com

volclog doctor

Notice

For stateless execution, use the one-time --secrets-file option as a priority. Do not inject a large number of environment variables into the entire session.

--profile and --secrets-file should not appear in the same command.

Clarify the contract.

First use tool and workflow to read the contract to avoid guessing inputs:

volclog tool list
volclog tool list project
volclog tool describe project.create

volclog workflow list
volclog workflow describe log.export

Only proceed directly to raw when method/path is already clarified:

volclog raw --method POST --path /CreateProject --body file://req.json

Notice

raw can accept --input as a compatible alias for --body, but --body and --input cannot be entered at the same time.

Pre-execution, execution, and filtering.

First perform a pre-execution with dry-run, then execute formally:

cat >ctx.json <<'EOF'
{
"region": "cn-beijing",
"execution": { "dry_run": true }
}
EOF

cat >req.json <<'EOF'
{
"ProjectName": "demo",
"Region": "cn-beijing"
}
EOF

volclog tool exec project.create --context file://ctx.json --input file://req.json

For large results, use file delivery as a priority:

olclog --output-mode file --output-dir ./out \
workflow exec log.export-analysis --input file://req.json

To project the envelope, use --jmes-filter:

volclog tool exec project.describe-projects \
--jmes-filter "data.Projects[].{ProjectId: ProjectId, ProjectName: ProjectName}"

Notice

--jmes-filter operates on the complete CLI envelope, so data.*, summary.*, and error.* are all valid paths.

If the target field exists but the value is null, stdout outputs the literal null and the command is still considered successful.

If the field does not exist, the object path is incorrect, or the array index is out of bounds, an error filter matched no value is reported.

--jmes-filter cannot be used together with file delivery.

Install skills

Built-in skills

The TLS CLI tool comes with an Agent Skill in the skills/ directory. Details are as follows:

Skill name

Description

volclog-core

When operating volclog via Agent/CI, read the contract before executing, rather than guessing flags and request bodies first. Used to implement contract-based workflows, enabling runtime selector parsing, discovery/description/execution routing, envelope reading, large result delivery, error recovery, and more.

This skill is only used to acquire incremental knowledge, that is, to supplement Agent incremental knowledge beyond tool describe and workflow describe, such as intent routing, cross-group SOP, runtime semantics, recovery strategies, and stateless credential integration methods.

Install skills

Use the following command to install the built-in skill:

volclog skill install --dir <agent-skills-dir>

To install a skill temporarily and clean up after use, use npx:

npx @volcengine-tls/volclog skill install --dir <agent-skills-dir>

Common capabilities

Common capabilities	Description
Prefer Agent workflows	By default, Agent prefers to use tool, workflow, and raw execution workflows. The human shortcut is still retained in volclog-human, but is not used as the default primary path.
Confirm contract before execution	Start from tool describe or workflow describe, confirm the contract, then prepare context and input.
Prioritize write operations	Before initiating a write operation, use --dry-run to preview the request shape and runtime selection, and submit the change request only after confirming correctness.
Prioritize large results	When stdout may output large results, use --output-mode file --output-dir <writable-dir> to write the results to a file.
Monitor runtime signals	Use summary.deliveryMode to determine whether the result is ultimately retained in stdout or has been automatically or forcibly written to a file.
Read error objects in order	In case of failure, check error.kind, error.code, error.message, and error.details in sequence to identify the cause of the error.
Explicitly specify region	Always explicitly specify the region to avoid relying on the endpoint to infer the region.

Last updated: 2026.09.10 17:22:09