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

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

Then use the acp-cli command directly:

acp-cli --version

From Source

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

Build Executable

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

Configuration

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

Via CLI

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:

{
  "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

# 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

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

# 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

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

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

Instance Management

# 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

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

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

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

# 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