# acp-cli

**Repository Path**: apusic-frontend/acp-cli

## Basic Information

- **Project Name**: acp-cli
- **Description**: 中间件管理平台ACP之命令行工具，让人类和 AI Agent 都能在终端中操作ACP。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# acp-cli

CLI tool for ACP platform — a command-line interface to interact with ACP's management, resource, and application operations APIs.

## Overview

`acp-cli` provides a unified command-line interface to three ACP backend services:

| Service | Port | Domain |
|---|---|---|
| **acp-manager** | 9800 | Platform management (auth, users, tenants, projects, workorders) |
| **acp-resource-manager** | 9800 | Resource management (VMs, hosts, clouds, quotas, images) |
| **acp-aump** | 9800 | Application operations (deployments, monitoring, security, software) |

All services are accessed through a unified gateway at `https://acp.apusic.com`.

## Installation

### From npm

```bash
npm install -g @apusic-cli/acp-cli
```

Then use the `acp-cli` command directly:
```bash
acp-cli --version
```

### From Source

```bash
npm install
npm run build
npm link        # Optional: register acp-cli as a global command
```

### Build Executable

```bash
npm run package
# Output: dist/acp-cli.exe
```

## Configuration

Configuration precedence: CLI flags > environment variables > config file > defaults.

### Via CLI

```bash
acp-cli settings show                       # View all settings
acp-cli settings get api-url                # Read a single setting
acp-cli settings set api-url <url>          # Update API URL
acp-cli settings set output <table|json|yaml>
acp-cli settings set timeout <ms>
acp-cli settings set debug <true|false>
```

### Config File

`~/.acp-cli/config.json`:

```json
{
  "apiUrl": "https://acp.apusic.com",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "timeout": 30000,
  "output": "table"
}
```

### Environment Variables

| Variable | Description | Default |
|---|---|---|
| `ACP_CLI_API_URL` | API base URL | `https://acp.apusic.com` |
| `ACP_CLI_TIMEOUT` | Request timeout (ms) | `30000` |
| `ACP_CLI_OUTPUT` | Output format | `table` |
| `ACP_CLI_DEBUG` | Enable debug logging | `false` |
| `ACP_CLI_TOKEN` | Bearer token for auth | *(empty)* |

## Usage

### Authentication

```bash
# Login and save token to ~/.acp-cli/config.json
acp-cli auth login -u <username> -p <password>

# Check current login status
acp-cli auth whoami

# Logout and clear token
acp-cli auth logout
```

### Global Options

```bash
acp-cli --api-url http://custom:8080 user list
acp-cli --output json vm list
acp-cli --output yaml deploy get 1
```

### Commands

#### Monitoring & Alerting

```bash
# Alert Policies & Rules
acp-cli alert policy-list [--page <n>] [--size <n>] [--name <n>] [--status <s>]
acp-cli alert policy-get <id>
acp-cli alert rule-list [--page <n>] [--size <n>] [--name <n>] [--group <g>] [--status <s>]

# Alert Events
acp-cli alert event-list [--page <n>] [--size <n>] [--name <n>] [--status <s>] [--severity <l>] [--start-time <d>] [--end-time <d>]
acp-cli alert event-overview

# Metrics & Dashboards
acp-cli monitor metrics --query '<promql>' [--start <ts>] [--end <ts>] [--step <s>]
acp-cli prometheus query --query '<promql>'
acp-cli grafana dashboard-list
acp-cli grafana dashboard-get <uid>
```

#### User Management

```bash
acp-cli user list
acp-cli user get <id>
acp-cli user create --username <name> --password <pass> --email <email>
acp-cli user delete <id>
```

#### VM Management

```bash
acp-cli vm list
acp-cli vm get <id>
acp-cli vm overview
```

#### Instance Management

```bash
# Basic CRUD
acp-cli instance list
acp-cli instance get <id>
acp-cli instance start <id>...
acp-cli instance stop <id>...
acp-cli instance restart <id>...
acp-cli instance delete <id>

# Configuration
acp-cli instance config get <id>         # fetch all config files
acp-cli instance config get <id> --name <file>  # fetch a specific config file
acp-cli instance config list <id>        # list config files
acp-cli instance config publish <id> --items '<json>'  # publish configuration (auto-merges with existing)
acp-cli instance config rollback <id>    # rollback configuration

# Logs
acp-cli instance log list <id>           # list log files
acp-cli instance log get <id>            # fetch default log
acp-cli instance log get <id> --name server.log --dir /opt/logs  # specific log file
acp-cli instance log get <id> -f         # tail logs (follow mode)
acp-cli instance log container <cid> --agent <agent> [--tail 100]  # Docker container logs
acp-cli instance logs <id>               # legacy alias for `instance log get`

# Environment & Health
acp-cli instance env get <id>            # get environment variables
acp-cli instance env set <id>            # set environment variables
acp-cli instance health get <id>         # get health check config
acp-cli instance events <id>             # get instance events
acp-cli instance volume list <id>        # list data volumes
acp-cli instance volume add <id>         # add data volume
```

#### Service Management

```bash
acp-cli service list
acp-cli service get <id>
acp-cli service deploy --name <n> --soft-name <n> --soft-version <v> --profile <p> --config <c> --replicas <json>
acp-cli service deploy --name <n> --soft-name <n> --soft-version <v> --profile <p> --config <c> --replicas-file <path>  # safer for complex JSON
acp-cli service start <id>...
acp-cli service stop <id>...
acp-cli service restart <id>...
acp-cli service delete <id>
acp-cli service upgrade <id>
```

**Note:** `service deploy` automatically validates preset packages when `presetsDetails` with `presetName` are included in `--replicas`. Missing presets are detected before the service is created. Use `--replicas-file` instead of inline `--replicas` to avoid shell quoting issues with complex JSON.

#### Preset Package Management

```bash
acp-cli preset check --project <p> --name <n> --preset-version <v> [--arch <a>]  # validate preset exists
acp-cli preset tree                                                       # list all preset packages
```

#### CLI Settings

```bash
acp-cli settings show
acp-cli settings get <key>
acp-cli settings set <key> <value>
```

Supported keys: `api-url`, `output`, `timeout`, `debug`

## Architecture

```
acp-cli/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── client/
│   │   ├── index.ts          # HTTP client (axios + Bearer auth + service routing)
│   │   ├── error.ts          # ApiError for unified error handling
│   │   └── types/            # TypeScript interfaces per service
│   ├── commands/             # Commander.js command modules
│   ├── config/               # Config loading/saving (convict)
│   └── output/               # Output formatters (table/json/yaml)
├── tests/                    # Unit tests (vitest)
└── docs/
    ├── superpowers/
    │   ├── specs/            # Architecture design document
    │   └── plans/            # Implementation plan
    └── features.md           # Feature status and roadmap
```

## Development

```bash
# Run tests
npm test

# Type-check only
npx tsc --noEmit

# Build
npm run build
```

## Tech Stack

- TypeScript 5.x
- Commander.js 11.x
- axios 1.6.x
- convict 6.2.x
- cli-table3 0.6.x
- js-yaml 4.1.x
- vitest 1.x

## License

Apache-2.0