### Install a Skill

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

Download and install a skill from the Nacos registry to your local machine. The skill is typically installed in ~/.skills/.

```bash
nacos-cli skill-get <skill-name>
```

--------------------------------

### Verify Skill Installation

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

After installation, you can confirm the skill is available by checking for its SKILL.md file in the specified directory.

```bash
ls ~/.skills/<skill-name>/SKILL.md
```

--------------------------------

### Connection Rule Example

Source: https://github.com/alibaba/nacos/blob/develop/specs/en/plugin/default-control-plugin-spec.md

Example JSON configuration for connection limiting. A countLimit below 0 allows all connections.

```json
{"countLimit":100}
```

--------------------------------

### Install Skill to Custom Path

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

If you need to install a skill to a specific directory other than the default, use the -o flag followed by the desired path.

```bash
nacos-cli skill-get <skill-name> -o /custom/path
```

--------------------------------

### Start Local Development Server

Source: https://github.com/alibaba/nacos/blob/develop/console-ui/README.md

Starts the local development server for the Nacos console UI. Proxy configuration is managed in `build/webpack.dev.conf.js`.

```bash
npm start
```

--------------------------------

### Install nacos-cli (Linux/macOS)

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

Install the nacos-cli tool globally on Linux or macOS using the provided installation script.

```bash
curl -fsSL https://nacos.io/nacos-installer.sh | sudo bash -s -- --cli
```

--------------------------------

### Connection Setup

Source: https://github.com/alibaba/nacos/blob/develop/specs/en/grpc-api/api-spec.md

Establishes a gRPC connection between the client and server. The initial payload must be `ConnectionSetupRequest`, which includes client version, namespace, labels, and an ability table. The server responds with `SetupAckRequest` containing server abilities.

```APIDOC
## stream BiRequestStream.requestBiStream

### Description
Initiates a bidirectional stream for gRPC communication. The first message sent must be `ConnectionSetupRequest` to establish the connection parameters.

### Request Payload
- **ConnectionSetupRequest**: Contains client version, namespace, labels, and ability table.

### Response Payload
- **SetupAckRequest**: Contains server abilities, sent in response to `ConnectionSetupRequest`.
```

--------------------------------

### Install nacos-cli (Windows)

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

Install the nacos-cli tool globally on Windows using PowerShell. This script downloads, executes, and cleans up the installer.

```powershell
iwr -UseBasicParsing https://nacos.io/nacos-installer.ps1 -OutFile $env:TEMP\nacos-installer.ps1; & $env:TEMP\nacos-installer.ps1 -cli; Remove-Item $env:TEMP\nacos-installer.ps1
```

--------------------------------

### Use Token in Subsequent Requests

Source: https://context7.com/alibaba/nacos/llms.txt

This example shows how to use an access token obtained previously in subsequent API requests.

```bash
curl -s "http://localhost:8848/nacos/v3/admin/cs/config?accessToken=${TOKEN}&dataId=app.yaml&groupName=DEFAULT_GROUP&namespaceId="

```

--------------------------------

### Start Local Development Server

Source: https://github.com/alibaba/nacos/blob/develop/console-ui-next/README.md

Starts the development server with hot-reloading. Visit http://localhost:8000. Vite proxy rules are configured to forward requests to the Nacos Admin and Console Servers.

```bash
npm run dev
```

--------------------------------

### Install Global CLI Tools

Source: https://github.com/alibaba/nacos/blob/develop/console-ui/README.md

Installs necessary global CLI tools for Nacos console UI development. Ensure Node.js version is compatible.

```bash
npm install -g cross-env webpack webpack-cli
```

--------------------------------

### Discover Instances (Client-Side Open API)

Source: https://context7.com/alibaba/nacos/llms.txt

Retrieve a list of instances for a service, used for client-side load balancing. Use `jq .` to pretty-print the JSON output.

```bash
# Discover instances (for client-side load balancing)
curl -s "http://localhost:8848/nacos/v3/client/ns/instance/list" \
  -G --data-urlencode "serviceName=payment-service" --data-urlencode "groupName=DEFAULT_GROUP" | jq .
```

--------------------------------

### Check nacos-cli Installation

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

Verify if the nacos-cli tool is installed on your system.

```bash
which nacos-cli
```

--------------------------------

### Create ConfigService Instance

Source: https://context7.com/alibaba/nacos/llms.txt

Demonstrates how to create a `ConfigService` instance using `NacosFactory.createConfigService(Properties)`. This involves setting essential properties like `serverAddr`, `namespace`, `username`, and `password`.

```APIDOC
## Java Client SDK — Create ConfigService

`NacosFactory.createConfigService(Properties)` creates a `ConfigService` instance connected to the Nacos server. Properties include `serverAddr`, `namespace`, `username`, `password`, and tuning parameters from `PropertyKeyConst`.

```java
import com.alibaba.nacos.api.NacosFactory;
import com.alibaba.nacos.api.config.ConfigService;
import com.alibaba.nacos.api.PropertyKeyConst;
import java.util.Properties;

Properties props = new Properties();
props.put(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
props.put(PropertyKeyConst.NAMESPACE, "dev-namespace-id"); // empty string = public
props.put(PropertyKeyConst.USERNAME, "nacos");
props.put(PropertyKeyConst.PASSWORD, "nacos");
props.put(PropertyKeyConst.CONFIG_LONG_POLL_TIMEOUT, "30000");

try {
    ConfigService configService = NacosFactory.createConfigService(props);
    System.out.println("Server status: " + configService.getServerStatus()); // "UP"
    configService.shutDown();
} catch (Exception e) {
    e.printStackTrace();
}
```
```

--------------------------------

### List Configurations (Admin v3)

Source: https://context7.com/alibaba/nacos/llms.txt

Search configurations using fuzzy matching. Supports pagination with pageNo/pageSize and filtering by dataId, groupName, type, and configDetail for content search. The 'search=blur' parameter enables fuzzy matching.

```bash
TOKEN="eyJhbGciOiJIUzI1NiJ9..."

# Search configs matching dataId prefix "service-" in DEFAULT_GROUP, page 1
curl -s "http://localhost:8848/nacos/v3/admin/cs/config/list?accessToken=${TOKEN}" \
  -G \
  --data-urlencode "dataId=service-" \
  --data-urlencode "groupName=DEFAULT_GROUP" \
  --data-urlencode "namespaceId=" \
  -d "search=blur" \
  -d "pageNo=1" \
  -d "pageSize=20" | jq .

```

--------------------------------

### TPS Rule Example

Source: https://github.com/alibaba/nacos/blob/develop/specs/en/plugin/default-control-plugin-spec.md

Example JSON configuration for TPS limiting. Specifies the point name, max count, and monitor type.

```json
{"pointName":"ConfigQuery","pointRule":{"maxCount":100,"monitorType":"intercept"}}
```

--------------------------------

### Create NamingService Instance

Source: https://context7.com/alibaba/nacos/llms.txt

Creates a `NamingService` instance for service registration and discovery. Requires properties such as server address, namespace, username, and password.

```java
import com.alibaba.nacos.api.NacosFactory;
import com.alibaba.nacos.api.naming.NamingService;
import java.util.Properties;

Properties props = new Properties();
props.put("serverAddr", "127.0.0.1:8848");
props.put("namespace", "production");
props.put("username", "nacos");
props.put("password", "nacos");

NamingService namingService = NacosFactory.createNamingService(props);
System.out.println(namingService.getServerStatus()); // "UP"
```

--------------------------------

### Nacos Controller Example

Source: https://github.com/alibaba/nacos/blob/develop/AGENTS.md

Example of a Nacos controller implementing service creation and listing endpoints. It utilizes `@Secured` for authentication and returns results wrapped in `Result<T>`.

```java
import com.alibaba.nacos.api.model.v2.Result;
import com.alibaba.nacos.auth.annotation.Secured;
import com.alibaba.nacos.plugin.auth.constant.ActionTypes;
import com.alibaba.nacos.plugin.auth.constant.SignType;
import com.alibaba.nacos.api.common.ApiType;

@RestController
@RequestMapping("/v3/admin/ns/service")
public class ServiceControllerV3 {

    @PostMapping
    @Secured(action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)
    public Result<String> create(ServiceForm serviceForm) throws Exception {
        serviceForm.validate();
        // business logic ...
        return Result.success("ok");
    }

    @GetMapping("/list")
    @Secured(action = ActionTypes.READ, apiType = ApiType.ADMIN_API)
    public Result<Page<ServiceDetailInfo>> list(ServiceListForm serviceListForm) throws NacosException {
        serviceListForm.validate();
        // business logic ...
        return Result.success(result);
    }
}
```

--------------------------------

### Verify Skill Directory

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

Before uploading, ensure the skill directory contains a valid SKILL.md file with the required frontmatter (name, description).

```bash
ls <path-to-skill>/SKILL.md
```

--------------------------------

### Start Nacos Server in Standalone Mode (Windows)

Source: https://github.com/alibaba/nacos/blob/develop/README.md

Starts the Nacos server in standalone mode on Windows. This can be done via the command line or by double-clicking the startup.cmd file.

```cmd
startup.cmd -m standalone
```

--------------------------------

### Start Nacos Server in Standalone Mode (Linux/Unix/Mac)

Source: https://github.com/alibaba/nacos/blob/develop/README.md

Starts the Nacos server in standalone mode on Linux, Unix, or Mac platforms. This is suitable for development and testing environments.

```sh
sh startup.sh -m standalone
```

--------------------------------

### Register Instance (Client-Side Open API)

Source: https://context7.com/alibaba/nacos/llms.txt

Register a service instance using the HTTP Open API, suitable for non-Java clients like Python or Go. Ephemeral instances require heartbeats to stay registered.

```bash
# Register from a Python/Go/Node.js service (no SDK available)
curl -s -X POST "http://localhost:8848/nacos/v3/client/ns/instance" \
  -d 'serviceName=python-worker' \
  -d 'groupName=DEFAULT_GROUP' \
  -d 'namespaceId=' \
  -d 'ip=10.0.2.15' \
  -d 'port=5000' \
  -d 'weight=1.0' \
  -d 'ephemeral=true'
```

--------------------------------

### Export and Import Configurations (Admin v3)

Source: https://context7.com/alibaba/nacos/llms.txt

Export all configurations as a ZIP archive or import a ZIP file to bulk-create configurations. The import operation supports collision policies like OVERWRITE, SKIP, and ABORT.

```bash
TOKEN="eyJhbGciOiJIUzI1NiJ9..."

# Export all configs in DEFAULT_GROUP as ZIP
curl -s -o nacos_backup.zip \
  "http://localhost:8848/nacos/v3/admin/cs/config/export?accessToken=${TOKEN}&groupName=DEFAULT_GROUP&namespaceId="

```

```bash
TOKEN="eyJhbGciOiJIUzI1NiJ9..."

# Import ZIP to another namespace (OVERWRITE on conflict)
curl -s -X POST "http://localhost:8848/nacos/v3/admin/cs/config/import?accessToken=${TOKEN}" \
  -F "file=@nacos_backup.zip" \
  -F "namespaceId=staging-namespace-id" \
  -F "policy=OVERWRITE"

```

--------------------------------

### Create Nacos Configuration (Aliyun Auth)

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

Manually create the default Nacos configuration file for 'aliyun' authentication type. Ensure you replace placeholders with actual user-provided values.

```bash
mkdir -p ~/.nacos-cli && cat > ~/.nacos-cli/default.conf << 'EOF'
host: <user-provided-host>
port: <user-provided-port>
authType: aliyun
accessKey: <user-provided-access-key>
secretKey: <user-provided-secret-key>
namespace: <user-provided-namespace>
EOF
```

--------------------------------

### Webpack Dev Proxy Configuration

Source: https://github.com/alibaba/nacos/blob/develop/console-ui/README.md

Example proxy configuration within `build/webpack.dev.conf.js` for development. It routes requests to a specified target.

```javascript
proxy: [{
  context: ['/'],
  changeOrigin: true,
  secure: false,
  target: 'http://ip:port',
}],
```

--------------------------------

### Unzip Nacos Server Package

Source: https://github.com/alibaba/nacos/blob/develop/README.md

Unzips the Nacos server binary package and navigates to the bin directory. This is a prerequisite for starting the Nacos server.

```sh
unzip nacos-server-1.0.0.zip
cd nacos/bin
```

--------------------------------

### List Service Instances (Admin v3)

Source: https://context7.com/alibaba/nacos/llms.txt

Retrieves all instances for a given service. Can be filtered by cluster and health status. Use `jq .` to pretty-print the JSON output.

```bash
TOKEN="eyJhbGciOiJIUzI1NiJ9..."

# List all instances of payment-service
curl -s "http://localhost:8848/nacos/v3/admin/ns/instance/list?accessToken=${TOKEN}" \
  -G \
  --data-urlencode "serviceName=payment-service" \
  --data-urlencode "groupName=DEFAULT_GROUP" \
  --data-urlencode "namespaceId=" \
  -d "healthyOnly=false" | jq .
```

--------------------------------

### Deploy Build Artifacts

Source: https://github.com/alibaba/nacos/blob/develop/console-ui-next/README.md

Copies the production build artifacts from the `dist/` directory to the backend's static resources directory for deployment.

```bash
rm -rf ../console/src/main/resources/static/next/*
cp -r dist/* ../console/src/main/resources/static/next/
```

--------------------------------

### Run nacos-cli via npx

Source: https://github.com/alibaba/nacos/blob/develop/skills/nacos-skill-registry/SKILL.md

Execute nacos-cli commands without global installation using npx. Replace 'nacos-cli' with 'npx @nacos-group/cli' for all commands.

```bash
npx @nacos-group/cli <command>
```

--------------------------------

### Nacos Configuration Properties

Source: https://context7.com/alibaba/nacos/llms.txt

These are example configuration properties for Nacos. Ensure the secret key is Base64-encoded and at least 32 characters long when auth is enabled.

```properties
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true
nacos.core.auth.system.type=nacos          # or: ldap, oidc
# Required when auth enabled — Base64-encoded secret (min 32 chars plain):
nacos.core.auth.plugin.nacos.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg=
nacos.core.auth.plugin.nacos.token.expire.seconds=18000

# nacos.member.list=192.168.1.1:8848,192.168.1.2:8848,192.168.1.3:8848

nacos.remote.server.grpc.sdk.max-inbound-message-size=10485760
nacos.remote.server.grpc.sdk.keep-alive-time=7200000

# nacos.extension.ai.enabled=true
# nacos.ai.mcp.registry.enabled=true
# nacos.ai.registry.port=9080

nacos.naming.empty-service.auto-clean=true
nacos.naming.empty-service.clean.period-time-ms=30000

# management.endpoints.web.exposure.include=prometheus
# nacos.prometheus.metrics.enabled=true
```

--------------------------------

### Enable Environment Plugin

Source: https://github.com/alibaba/nacos/blob/develop/specs/en/plugin/environment-plugin-spec.md

Configure this property to enable the environment plugin.

```properties
nacos.custom.environment.enabled=true
```

--------------------------------

### Query Configuration (Admin v3)

Source: https://context7.com/alibaba/nacos/llms.txt

Retrieve full details of a single configuration, including its content, MD5 hash, type, and history metadata. Ensure the dataId, groupName, and namespaceId are correctly specified.

```bash
TOKEN="eyJhbGciOiJIUzI1NiJ9..."

curl -s "http://localhost:8848/nacos/v3/admin/cs/config?accessToken=${TOKEN}" \
  -G \
  --data-urlencode "dataId=database.properties" \
  --data-urlencode "groupName=DEFAULT_GROUP" \
  --data-urlencode "namespaceId=" | jq .

```

--------------------------------

### Spring Cloud Nacos Application Configuration

Source: https://context7.com/alibaba/nacos/llms.txt

Configure Nacos server address, credentials, and namespaces for config and discovery in your application.yml. This example sets up a 'dev-namespace-id' and 'DEFAULT_GROUP'.

```yaml
spring:
  application:
    name: my-service
  cloud:
    nacos:
      server-addr: 127.0.0.1:8848
      username: nacos
      password: nacos
      config:
        namespace: dev-namespace-id
        group: DEFAULT_GROUP
        file-extension: yaml
        # Loads: ${spring.application.name}.yaml = my-service.yaml
      discovery:
        namespace: dev-namespace-id
        group: DEFAULT_GROUP
        metadata:
          version: "1.0"
          zone: us-east
```

--------------------------------

### Get Configuration Content

Source: https://context7.com/alibaba/nacos/llms.txt

Retrieve configuration content using getConfig or getConfigWithResult. getConfigWithResult also provides the MD5 hash, which is useful for Compare-And-Swap (CAS) operations during publishing.

```java
ConfigService configService = NacosFactory.createConfigService("127.0.0.1:8848");

// Simple fetch
String content = configService.getConfig("application.yaml", "DEFAULT_GROUP", 5000);
System.out.println(content);
// Expected: "server:\n  port: 8080\n..."

// Fetch with MD5 for CAS publishing
var result = configService.getConfigWithResult("application.yaml", "DEFAULT_GROUP", 5000);
System.out.println("Content: " + result.getContent());
System.out.println("MD5: " + result.getMd5());

// Publish with CAS guard (only update if MD5 matches current)
boolean published = configService.publishConfigCas(
    "application.yaml", "DEFAULT_GROUP",
    "server:\n  port: 9090\n",
    result.getMd5(),      // casMd5
    "yaml"
);
System.out.println("CAS publish succeeded: " + published);
```