@nacos-group/cli 1.0.4-beta.1 → 1.0.5-beta.1

package/README.md

@@ -6,12 +6,13 @@ A powerful command-line tool for managing Nacos configuration center and AI skil
 
 - 🚀 Fast and lightweight - single binary with no dependencies
 - 💻 Interactive terminal mode with auto-completion
-- 🎯 Skill management - upload, download, list, and sync AI skills
-- 🤖 AgentSpec management - upload, download, and list AI agent specs
-- 📝 Configuration management - list and get configurations
+- 🎯 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
 
@@ -87,18 +88,37 @@ nacos> help
 
 ### AgentSpec Management
 
+Agent specs follow a three-stage lifecycle aligned with the server:
+`upload` (editing) → `review` (reviewing → reviewed) → `release` (online).
+
 #### List AgentSpecs
 
 ```bash
-# CLI mode (description shown by default, truncated at 200 chars)
+# 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):
+
+```bash
+nacos-cli agentspec-describe my-agentspec
+nacos-cli agentspec-describe my-agentspec --output json
+
+# Terminal mode
+nacos> agentspec-describe my-agentspec
 ```
 
 #### Get/Download AgentSpec
@@ -123,36 +143,96 @@ nacos-cli agentspec-get spec1 spec2 spec3
 nacos> agentspec-get my-agentspec
 ```
 
-#### Publish AgentSpec
+#### Upload AgentSpec
 
-Publish an agent spec from local directory:
+Upload an agent spec from local directory (creates or updates the `editing` version):
 
 ```bash
-# Publish single agent spec
-nacos-cli agentspec-publish /path/to/agentspec -s 127.0.0.1:8848 -u nacos -p nacos
+# Upload single agent spec
+nacos-cli agentspec-upload /path/to/agentspec -s 127.0.0.1:8848 -u nacos -p nacos
 
-# Publish all agent specs in a directory
-nacos-cli agentspec-publish --all /path/to/agentspecs/folder
+# 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`.
+
+```bash
+nacos-cli agentspec-review my-agentspec
 
 # Terminal mode
-nacos> agentspec-publish /path/to/agentspec
-nacos> agentspec-publish --all /path/to/agentspecs
+nacos> agentspec-review my-agentspec
+```
+
+#### Release AgentSpec
+
+Publish an approved (reviewed) version online:
+
+```bash
+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.
+
+```bash
+# 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
 
 ```bash
-# CLI mode (description shown by default, truncated at 200 chars)
+# 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
+
+```bash
+nacos-cli skill-describe skill-creator
+nacos-cli skill-describe skill-creator --output json
+
+# Terminal mode
+nacos> skill-describe skill-creator
 ```
 
 #### Get/Download Skill
@@ -170,7 +250,7 @@ nacos> skill-get skill-creator
 
 #### Upload Skill
 
-Upload a skill from local directory:
+Upload a skill from local directory (creates or updates the `editing` version):
 
 ```bash
 # Upload single skill
@@ -184,6 +264,44 @@ nacos> skill-upload /path/to/skill
 nacos> skill-upload --all /path/to/skills
 ```
 
+#### Review Skill
+
+Submit the current editing version for review (editing → reviewing):
+
+```bash
+nacos-cli skill-review skill-creator
+
+# Terminal mode
+nacos> skill-review skill-creator
+```
+
+#### Release Skill
+
+Publish an approved (reviewed) version online:
+
+```bash
+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`.
+
+#### Publish Skill (deprecated)
+
+`skill-publish` is kept as a backward-compatible shortcut that runs
+`upload` + `review` in sequence. Prefer the explicit lifecycle commands.
+
+```bash
+# 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:
@@ -302,10 +420,20 @@ namespace: ""
 Configuration values are applied in the following priority order:
 1. **Command line arguments** (highest priority)
 2. **Configuration file**
-3. **Default values** (lowest priority)
+3. **Environment variables**
+4. **Default values** (lowest priority)
+
+Supported environment variables:
+
+```bash
+export NACOS_HOST=127.0.0.1
+export NACOS_PORT=8848
+export NACOS_NAMESPACE=xxx
+```
 
 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
@@ -315,26 +443,36 @@ For example:
 
 ```
 nacos-cli/
-├── cmd/                  # CLI commands
-│   ├── root.go          # Root command
-│   ├── list_skill.go    # skill-list command  
-│   ├── get_skill.go     # skill-get command
-│   ├── upload_skill.go  # skill-upload command
-│   ├── sync_skill.go    # skill-sync command
-│   ├── list_agentspec.go   # agentspec-list command
-│   ├── get_agentspec.go    # agentspec-get command
-│   ├── publish_agentspec.go # agentspec-publish command
-│   ├── list_config.go   # config-list command
-│   ├── get_config.go    # config-get command
-│   └── interactive.go   # Interactive terminal
+├── 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
+│   ├── 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/        # Terminal implementation
-│   └── help/            # Help system
+│   ├── 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
@@ -383,6 +521,16 @@ MIT License
 
 ## Changelog
 
+### 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

package/bin/cli.js

@@ -7,7 +7,7 @@ const os = require('os');
 
 // Fixed nacos-cli binary version
 // npm package version is independent from binary version
-const VERSION = '1.0.4-beta.1';
+const VERSION = '1.0.5-beta.1';
 
 // Detect platform and architecture
 function getBinaryName() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nacos-group/cli",
-  "version": "1.0.4-beta.1",
+  "version": "1.0.5-beta.1",
   "description": "A command-line tool for managing Nacos configurations and AI skills",
   "bin": {
     "nacos-cli": "./bin/cli.js"