Release v0.1.0

🎉 ecctl v0.1.0 - Initial Release

Agent-first command-line control for Alibaba Cloud elastic computing resources.

We are pleased to publish the first release of ecctl, a resource-oriented CLI for agents, scripts, and operators working with Alibaba Cloud elastic computing services. ecctl provides a consistent product, resource, and action grammar, JSON-first results, locally inspectable schemas, structured errors, and synchronous resource operations.

✨ Highlights

• 🤖 Agent-First Discovery: Inspect products, resources, actions, required inputs, risk, dry-run support, idempotency, waiters, and output contracts locally before making a cloud API call.
• ☁️ Broad Public Resource Coverage: Manage 4 Alibaba Cloud products through 27 public resource interfaces and 142 modeled actions across ACK, ECS, Lingjun, and VPC.
• 🔄 Synchronous Resource Operations: Mutations can wait for the target state and read the resource back before returning, with --no-wait and --timeout available when the command contract supports them.
• 📦 JSON-First Automation: Results, pagination, cloud API actions, request IDs, capabilities used, and normalized failures are exposed as structured JSON by default.
• 🛡️ Safer Cloud Changes: Command schemas declare risk and expose supported controls such as --dry-run, --idempotency-key, and --force.
• 🔍 Raw OpenAPI Escape Hatch: Use ecctl call to inspect and invoke Alibaba Cloud OpenAPI operations that are not yet modeled as resource commands.
• 🌍 English and Simplified Chinese: Help, command descriptions, validation messages, and documentation are available in English and Simplified Chinese.
• 💻 Cross-Platform Distribution: Pre-built archives cover macOS, Linux, and Windows on AMD64 and ARM64, with SHA-256 checksums for verification.

🚀 Quick Start

Install the Exact Version with Go

Go 1.25 or later is required:

go install github.com/aliyun/elastic-compute-control-cli/cmd/ecctl@v0.1.0

You can also download a pre-built archive for your operating system and architecture from the assets attached to this Release.

Inspect the CLI Before Running Cloud Operations

ecctl schema --list
ecctl schema --list ecs
ecctl schema ecs.instance.create --brief
ecctl capabilities --output json

Configure a Profile

ecctl can reuse a compatible Alibaba Cloud CLI profile or maintain its own configuration:

ecctl configure set region cn-hangzhou
ecctl configure set output json
ecctl configure get

Use --profile to select a named profile and --region to override the configured region for one command.

Run Resource Commands

# List running ECS instances
ecctl ecs instance list --filter status=Running --region cn-hangzhou

# Inspect one VPC
ecctl vpc get <vpc-id> --region cn-hangzhou

# List ACK clusters
ecctl ack list --region cn-hangzhou

🧭 Command Model

Resource commands follow a regular grammar:

ecctl <product> [<parent>] <resource> <action> [id] [flags]

Some products expose shorter forms for their default resource. For example, ecctl ack list is the short form of the ACK cluster list operation, and ecctl vpc list addresses the default VPC resource.

Command	Purpose
ecctl schema --list [product]	List public products, resources, and actions
ecctl schema <schema-id> --brief	Inspect the concise machine-readable contract for one action
ecctl schema <schema-id> --full	Inspect all schema-visible parameters and behavior
ecctl capabilities --output json	Describe the public surface, output modes, and structured error contract
ecctl configure	Manage profiles, credentials, region, language, and default output
ecctl call	Inspect or invoke raw Alibaba Cloud OpenAPI operations
ecctl completion	Generate shell completion scripts

☁️ Public Resource Coverage

ACK

Resource	Actions
ack	list, get, create, update, delete, upgrade
kubeconfig	list, get, create, update, revoke
node	list, get, delete, attach
nodepool	list, get, create, update, delete, attach, detach, repair, upgrade
permission	list, get, update, delete
region	list
version	list

ACK coverage includes cluster lifecycle operations, kubeconfig credentials, node and node pool management, RAM permissions, supported regions, and Kubernetes version metadata.

ECS

Resource	Actions
assistant	get, update, install
auto-snapshot-policy	list, get, create, update, delete
command	list, get, create, update, delete, invoke, stop
disk	list, get, create, update, delete, attach, clone, detach, monitor, reinit, reset
eni	list, get, create, update, delete, attach, detach
image	list, get, create, update, delete, copy, export, import
instance	list, get, create, update, delete, exec, monitor, reboot, renew, sendfile, start, stop
keypair	list, get, create, delete
launch-template	list, get, create, update, delete
port-range-list	list, get, create, update, delete
prefix-list	list, get, create, update, delete
region	list
sg	list, get, create, update, delete, authorize, revoke
snapshot	list, get, create, update, delete, copy
snapshot-group	list, get, create, update, delete
zone	list

ECS coverage includes compute instances, disks, snapshots, images, security groups, elastic network interfaces, SSH key pairs, launch templates, Cloud Assistant commands, automatic snapshot policies, port range lists, prefix lists, regions, and zones.

Lingjun and VPC

Product	Resource	Actions
Lingjun	cluster	list, get, create, update, delete
Lingjun	vpd	list, get, create, update, delete
VPC	vpc	list, get, create, update, delete
VPC	vswitch	list, get, create, update, delete

The public Lingjun surface covers clusters and VPD networks. The VPC surface covers isolated networks and zone-level vSwitch subnets.

🛡️ Operational Contracts and Safety

Inspectable Contracts

Each modeled action can describe:

• Required and optional parameters
• Canonical output command form
• Risk level
• Dry-run availability
• Idempotency behavior
• Waiter target state, polling command, and default timeout
• Normalized output fields

Use the schema as the source of truth because controls vary by product, resource, and action.

Wait and Read Back

Many Alibaba Cloud mutation APIs return before a resource reaches its final state. Where modeled, ecctl waits for the target state, records the API calls under actions, and returns the final resource view. Pass --no-wait for asynchronous behavior or --timeout <duration> to change the waiting limit when those flags are exposed.

Dry Run and Idempotency

Commands whose contracts declare dry-run support accept --dry-run. Mutations that support client-token idempotency accept --idempotency-key <token>, allowing a caller to retry without creating duplicate resources.

Pagination and Filtering

List commands use a common --filter key=value form. JSON responses expose pagination details including the current page, limit, returned count, and whether more results are available.

Structured Errors

Failures are written as structured JSON and return a non-zero exit code. The error object can include:

Field	Meaning
kind	Error category such as client, not_found, or service
code	Stable error code
message	User-facing explanation
retryable	Whether retrying is appropriate
suggestion	Human-readable corrective guidance
suggested_action	Machine-oriented next step
field	Related input field
accepted_values	Valid values for the field

When a cloud API call fails, the actions entries preserve the operation name, request ID, service code, and service message.

📦 Output, Configuration, and Distribution

Output and Language Options

Option	Description
`--output json	text`
--json	Force JSON output
--agent-envelope	Wrap JSON in the ecctl Agent envelope
`--lang en	zh-CN`
--profile <name>	Select a configuration profile
--region <region-id>	Select a region for the current command
--no-color	Disable color in human-readable output

ECCTL_DISPLAY_MODE=AI or ECCTL_DISPLAY_MODE=agent enables compact, non-highlighted output for agents and automation. Human terminal output uses pretty JSON and highlighted text by default, while redirected output automatically favors the compact representation.

Configuration

ecctl supports named profiles, masks stored secrets by default, and can read a compatible local Alibaba Cloud CLI configuration. Environment variables can override the active profile, region, and Alibaba Cloud configuration path.

Release Assets

Operating System	Architectures	Archive
macOS	AMD64, ARM64	.tar.gz
Linux	AMD64, ARM64	.tar.gz
Windows	AMD64, ARM64	.zip

The Release includes checksums.txt with SHA-256 hashes for all archives. The product repository also acts as the Homebrew Tap for current releases:

brew tap aliyun/ecctl https://github.com/aliyun/elastic-compute-control-cli
brew install ecctl

Homebrew follows the current public Cask and may install a version newer than v0.1.0. The macOS binaries in this initial release are not signed or notarized.

🔧 Technical Details

• Release tag: v0.1.0
• Release commit: 8a750e4c0241b6a69bbfd13732d8476719f308a8
• Public products: ACK, ECS, Lingjun, VPC
• Public resource interfaces: 27
• Modeled public actions: 142
• Schema version: 1
• Default output: JSON
• Languages: English and Simplified Chinese
• Go version: 1.25 or later
• License: Apache 2.0

📚 Documentation

• Getting Started
• Installation
• Concepts
• Command Discovery
• Resource Operations
• Resource Coverage
• Resource Spec Guide