Nacos CLI

June 4, 2026 · View on GitHub

A powerful command-line tool for managing Nacos configuration center and AI skills, written in Go.

Features

🚀 Fast and lightweight - single binary with no dependencies
💻 Interactive terminal mode with auto-completion
🎯 Skill management - full lifecycle: upload → review → release, plus get/list/describe/sync
🤖 AgentSpec management - full lifecycle: upload → review → release, plus get/list/describe
📝 Configuration management - list, get and set configurations
🔄 Real-time skill synchronization with Nacos
🌐 Namespace support for multi-environment management
📦 Batch operations - upload all skills and agent specs at once
🧾 Structured output - --output json on list/describe for scripting

Installation

npm / npx

Use npx to run directly without installation:

npx @nacos-group/cli --help
npx @nacos-group/cli skill-list --host 127.0.0.1 --port 8848 -u nacos -p nacos

Or install globally via npm:

npm install -g @nacos-group/cli
nacos-cli --help

Download Binary

Download the latest release from GitHub Releases.

Build from Source

# Clone the repository
git clone https://github.com/nacos-group/nacos-cli.git
cd nacos-cli

# Build
go build -o nacos-cli

# Or use make
make build

Quick Start

CLI Mode

Run commands directly:

# List all skills
nacos-cli skill-list -s 127.0.0.1:8848 -u nacos -p nacos

# Get a skill
nacos-cli skill-get skill-creator -s 127.0.0.1:8848 -u nacos -p nacos

# Upload a skill
nacos-cli skill-upload /path/to/skill -s 127.0.0.1:8848 -u nacos -p nacos

Interactive Terminal Mode

Start an interactive session:

nacos-cli -s 127.0.0.1:8848 -u nacos -p nacos

Once in terminal mode, you can run commands interactively:

nacos> skill-list
nacos> skill-get skill-creator
nacos> config-list
nacos> help

HTTPS Support

Connect to Nacos servers over HTTPS (e.g., behind a TLS-terminating gateway or K8s Ingress):

# Explicit --scheme flag
nacos-cli skill-list --host nacos.example.com --port 443 --scheme https -u nacos -p nacos

# Auto-detect from host prefix (scheme is inferred automatically)
nacos-cli skill-list --host https://nacos.example.com:443 -u nacos -p nacos

# Via profile configuration
nacos-cli --profile prod skill-list

# Via environment variable
NACOS_SCHEME=https nacos-cli skill-list --host nacos.example.com --port 443 -u nacos -p nacos

Scheme resolution priority (highest to lowest):

--scheme command-line flag
Auto-detected from --host prefix (https://...)
Profile config file scheme field
NACOS_SCHEME environment variable
Default: http

Commands

AgentSpec Management

Agent specs follow a three-stage lifecycle aligned with the server: upload (editing) → review (reviewing → reviewed) → release (online).

List AgentSpecs

# CLI mode (pretty output by default)
nacos-cli agentspec-list -s 127.0.0.1:8848 -u nacos -p nacos

# With filters
nacos-cli agentspec-list --name my-agentspec --page 1 --size 20

# Machine-readable output for scripts
nacos-cli agentspec-list --output json

# Terminal mode
nacos> agentspec-list
nacos> agentspec-list --name my-agentspec --page 2
nacos> agentspec-list --output json

Describe AgentSpec

Show detail + version history (latest / editing / reviewing / online, plus per-version status):

nacos-cli agentspec-describe my-agentspec
nacos-cli agentspec-describe my-agentspec --output json

# Terminal mode
nacos> agentspec-describe my-agentspec

Get/Download AgentSpec

Download an agent spec to local directory (default: ~/.agentspecs):

# CLI mode
nacos-cli agentspec-get my-agentspec -s 127.0.0.1:8848 -u nacos -p nacos
nacos-cli agentspec-get my-agentspec -o /custom/path

# Download specific version
nacos-cli agentspec-get my-agentspec --version v1

# Download by route label
nacos-cli agentspec-get my-agentspec --label latest

# Download multiple agent specs
nacos-cli agentspec-get spec1 spec2 spec3

# Terminal mode
nacos> agentspec-get my-agentspec

Upload AgentSpec

Upload an agent spec from local directory (creates or updates the editing version):

# Upload single agent spec
nacos-cli agentspec-upload /path/to/agentspec -s 127.0.0.1:8848 -u nacos -p nacos

# Upload all agent specs in a directory
nacos-cli agentspec-upload --all /path/to/agentspecs/folder

# Terminal mode
nacos> agentspec-upload /path/to/agentspec
nacos> agentspec-upload --all /path/to/agentspecs

Review AgentSpec

Submit the current editing version for review (editing → reviewing). The server-side review pipeline is asynchronous and eventually marks the version as reviewed.

nacos-cli agentspec-review my-agentspec

# Terminal mode
nacos> agentspec-review my-agentspec

Release AgentSpec

Publish an approved (reviewed) version online:

nacos-cli agentspec-release my-agentspec --version 0.0.2
nacos-cli agentspec-release my-agentspec --version 0.0.2 --update-latest=false

# Terminal mode
nacos> agentspec-release my-agentspec --version 0.0.2

Note: if agentspec-release fails with HTTP 400 parameter validate error right after agentspec-review, the async review pipeline probably hasn't marked the version as reviewed yet. The CLI will print a hint telling you to wait a few seconds and re-check status via agentspec-describe. Retry when STATUS=reviewed.

Publish AgentSpec (deprecated)

agentspec-publish is kept as a backward-compatible shortcut that runs upload + review in sequence. It prints a deprecation warning and will be removed in a future release — prefer the explicit lifecycle commands above.

# Legacy shortcut (deprecated)
nacos-cli agentspec-publish /path/to/agentspec
nacos-cli agentspec-publish --all /path/to/agentspecs/folder

Skill Management

Skills follow the same three-stage lifecycle as agent specs: upload (editing) → review (reviewing → reviewed) → release (online).

List Skills

# CLI mode (pretty output by default)
nacos-cli skill-list -s 127.0.0.1:8848 -u nacos -p nacos

# With filters
nacos-cli skill-list --name skill-creator --page 1 --size 20

# Machine-readable output for scripts
nacos-cli skill-list --output json

# Terminal mode
nacos> skill-list
nacos> skill-list --name skill-creator --page 2
nacos> skill-list --output json

Describe Skill

nacos-cli skill-describe skill-creator
nacos-cli skill-describe skill-creator --output json

# Terminal mode
nacos> skill-describe skill-creator

Get/Download Skill

Download a skill to local directory (default: ~/.skills):

# CLI mode
nacos-cli skill-get skill-creator -s 127.0.0.1:8848 -u nacos -p nacos
nacos-cli skill-get skill-creator -o /custom/path

# Terminal mode
nacos> skill-get skill-creator

Upload Skill

Upload a skill from local directory (creates or updates the editing version):

# Upload single skill
nacos-cli skill-upload /path/to/skill -s 127.0.0.1:8848 -u nacos -p nacos

# Upload all skills in a directory
nacos-cli skill-upload --all /path/to/skills/folder

# Terminal mode
nacos> skill-upload /path/to/skill
nacos> skill-upload --all /path/to/skills

Review Skill

Submit the current editing version for review (editing → reviewing):

nacos-cli skill-review skill-creator

# Terminal mode
nacos> skill-review skill-creator

Release Skill

Publish an approved (reviewed) version online:

nacos-cli skill-release skill-creator --version 0.0.2
nacos-cli skill-release skill-creator --version 0.0.2 --update-latest=false

# Terminal mode
nacos> skill-release skill-creator --version 0.0.2

Same async-pipeline note as agentspec-release: if skill-release returns HTTP 400 parameter validate error just after skill-review, wait and retry when skill-describe shows the version as reviewed.

Manage Skill Visibility and Tags

Set skill visibility scope:

nacos-cli skill-scope skill-creator --scope PUBLIC
nacos-cli skill-scope skill-creator --scope PRIVATE

# Terminal mode
nacos> skill-scope skill-creator --scope PUBLIC

Set skill metadata tags:

nacos-cli skill-tags skill-creator --tags retail,finance

# Terminal mode
nacos> skill-tags skill-creator --tags retail,finance

Publish Skill (deprecated)

skill-publish is kept as a backward-compatible shortcut that runs upload + review in sequence. Prefer the explicit lifecycle commands.

# Legacy shortcut (deprecated)
nacos-cli skill-publish /path/to/skill
nacos-cli skill-publish --all /path/to/skills/folder

Sync Skill

Real-time synchronization - automatically syncs local skills when they change in Nacos:

# Sync single skill (CLI mode only)
nacos-cli skill-sync skill-creator -s 127.0.0.1:8848 -u nacos -p nacos

# Sync multiple skills
nacos-cli skill-sync skill-creator skill-analyzer

# Sync all skills
nacos-cli skill-sync --all

# Press Ctrl+C to stop synchronization

Note: skill-sync is only available in CLI mode, not in terminal mode.

Configuration Management

List Configurations

# CLI mode
nacos-cli config-list -s 127.0.0.1:8848 -u nacos -p nacos

# With filters
nacos-cli config-list --data-id myconfig --group DEFAULT_GROUP

# With pagination
nacos-cli config-list --page 1 --size 20

# Terminal mode
nacos> config-list
nacos> config-list --data-id myconfig --page 2

Get Configuration

# CLI mode
nacos-cli config-get myconfig DEFAULT_GROUP -s 127.0.0.1:8848 -u nacos -p nacos

# Terminal mode
nacos> config-get myconfig DEFAULT_GROUP

Terminal Commands

When in interactive terminal mode:

nacos> help           # Show all available commands
nacos> server         # Show server information
nacos> ns             # Show current namespace
nacos> ns production  # Switch to production namespace
nacos> clear          # Clear screen
nacos> quit           # Exit terminal

Global Flags

Flag	Short	Default	Description
--host		market.hiclaw.io when `--host` and `--port` are both omitted; otherwise 127.0.0.1 when only `--port` is provided	Nacos server host
--port		80 when `--host` and `--port` are both omitted; otherwise 8848 when omitted after `--host`	Nacos server port
--scheme		http	Protocol scheme: `http` or `https`
--server	-s	market.hiclaw.io:80 when no host/port is provided	Nacos server address (deprecated, use --host and --port)
--username	-u	nacos	Nacos username
--password	-p	nacos	Nacos password
--namespace	-n	(empty/public)	Nacos namespace ID
--config	-c		Path to configuration file
--help	-h		Show help information

Profile Configuration

Use profile edit to create or update a profile configuration:

# Create or update the current profile
nacos-cli profile edit

# Create or update a named profile
nacos-cli profile edit dev

# Use a profile once
nacos-cli --profile dev skill-list

# Switch the default profile used when --profile is omitted
nacos-cli profile switch dev

Profile files are stored under ~/.nacos-cli/<profile>.conf. They are YAML files managed by the CLI, and sensitive fields are encrypted before they are saved.

Example generated profile:

host: 127.0.0.1
port: 8848
scheme: http          # http or https (default: http)
authType: nacos
username: ENC[v1:aes-256-gcm:...]
password: ENC[v1:aes-256-gcm:...]
namespace: ""

Sensitive fields (username, password, accessKey, secretKey, and securityToken) are encrypted with AES-256-GCM before being saved by the CLI. The local encryption key is stored at ~/.nacos-cli/key with 0600 permissions. Existing plaintext config files remain readable for backward compatibility; the next profile load or profile edit rewrites sensitive fields in encrypted form.

Profile management commands:

# List profiles
nacos-cli profile list
nacos-cli profile list --output json

# Show or read profile values
nacos-cli profile show dev
nacos-cli profile get dev server
nacos-cli profile get auth-type

# Non-interactively create or update profile values
nacos-cli profile set dev host=127.0.0.1 port=8848 auth-type=none
nacos-cli profile set dev auth-type=nacos username=nacos password=nacos
nacos-cli profile set dev server=127.0.0.1:8848 namespace=public

# Delete a profile
nacos-cli profile delete dev

Configuration Priority

Configuration values are applied in the following priority order:

Command line arguments (highest priority)
Explicit --profile or --config file
Current profile selected by profile switch
Environment variables
Default values (lowest priority)

Supported environment variables:

export NACOS_HOST=127.0.0.1
export NACOS_PORT=8848
export NACOS_NAMESPACE=xxx
export NACOS_SCHEME=https    # http or https (default: http)

For example:

nacos-cli --config ./local.conf --host 10.0.0.1 - Uses 10.0.0.1 from command line, other values from config file
NACOS_HOST=127.0.0.1 NACOS_PORT=8848 NACOS_NAMESPACE=xxx nacos-cli skill-list - Uses environment variables when command line and config file values are not provided
nacos-cli - Uses default market.hiclaw.io:80 when neither --host nor --port is provided
nacos-cli --host 127.0.0.1 - Uses 127.0.0.1:8848 because --host was provided without --port
nacos-cli --port 8849 - Uses 127.0.0.1:8849 because only --port was provided
nacos-cli --config ./local.conf - Uses all values from config file

Project Structure

nacos-cli/
├── cmd/                       # CLI commands
│   ├── root.go                # Root command / global flags
│   ├── list_skill.go          # skill-list
│   ├── describe_skill.go      # skill-describe
│   ├── get_skill.go           # skill-get
│   ├── upload_skill.go        # skill-upload
│   ├── review_skill.go        # skill-review
│   ├── release_skill.go       # skill-release
│   ├── update_skill_scope.go  # skill-scope
│   ├── update_skill_tags.go   # skill-tags
│   ├── publish_skill.go       # skill-publish (deprecated wrapper)
│   ├── sync_skill.go          # skill-sync
│   ├── list_agentspec.go      # agentspec-list
│   ├── describe_agentspec.go  # agentspec-describe
│   ├── get_agentspec.go       # agentspec-get
│   ├── upload_agentspec.go    # agentspec-upload
│   ├── review_agentspec.go    # agentspec-review
│   ├── release_agentspec.go   # agentspec-release
│   ├── publish_agentspec.go   # agentspec-publish (deprecated wrapper)
│   ├── list_config.go         # config-list
│   ├── get_config.go          # config-get
│   ├── set_config.go          # config-set
│   ├── profile.go             # profile / config file handling
│   └── interactive.go         # Interactive terminal entry
├── internal/
│   ├── client/                # Nacos client
│   ├── skill/                 # Skill service
│   ├── agentspec/             # AgentSpec service
│   ├── sync/                  # Sync service
│   ├── listener/              # Config listener
│   ├── terminal/              # Interactive terminal implementation
│   └── help/                  # Help system
├── main.go
├── go.mod
└── README.md

Development

Prerequisites

Go 1.21 or higher
Nacos server (2.x recommended)

Build

# Build binary
make build

# Or manually
go build -o nacos-cli

Run Tests

# Run test script
./test.sh

# Or test specific commands
go run main.go skill-list -s 127.0.0.1:8848 -u nacos -p nacos

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Fixed skill-upload and agentspec-upload creating ZIP archives with an extra directory prefix, causing server-side extraction failures (#46)
Fixed ZIP archive paths using OS-native backslashes on Windows, violating the ZIP specification's forward-slash requirement (#26)
Added HTTPS support via --scheme flag, profile scheme field, and NACOS_SCHEME environment variable (#57)
Auto-detect scheme from --host URL prefix (e.g. --host https://nacos.example.com)
All 22 hardcoded http:// URL constructions replaced with configurable scheme

v1.0.4 (2026-05-08)

Aligned agentspec-* commands with skill-* around the full server lifecycle (upload → review → release), plus new agentspec-describe / skill-describe
Added --output pretty|json on *-list and *-describe for scripting
agentspec-publish / skill-publish are now deprecated wrappers that run upload + review and emit a deprecation warning
*-release now prints a targeted hint when failing with HTTP 400 parameter validate error, pointing to the async review pipeline timing issue

v0.2.0 (2026-01-28)

Rewritten in Go for better performance and portability
Added skill management commands (list, get, upload, sync)
Added agent spec management commands (list, get, upload)
Added real-time skill synchronization with Nacos
Added interactive terminal mode with auto-completion
Added batch upload support for multiple skills and agent specs
Added configuration management commands
Improved error handling and user experience
Removed all emoji clutter from terminal output

v0.1.0 (2026-01-27)

Initial Python version release
Basic configuration management
Basic service discovery