mirror of
https://gitee.com/pnoker/iot-dc3.git
synced 2026-11-01 10:41:52 +08:00
pnoker
eae86b58fc
- migrate auth, manager, data, and agentic persistence to R2DBC - hard cut pagination, facade, gateway, web, and CLI contracts - remove legacy database and TSDB adapters and document validation gates BREAKING CHANGE: platform persistence now requires PostgreSQL 18 with TimescaleDB and the new reactive API contracts.
307 lines
10 KiB
Markdown
307 lines
10 KiB
Markdown
# dc3-cli
|
|
|
|
IoT DC3 Platform CLI — AI-ready command-line interface for the DC3 IoT platform.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install -g dc3-cli
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Configure the gateway
|
|
dc3 config set gateway http://localhost:8000
|
|
|
|
# 2. Log in
|
|
dc3 auth login
|
|
|
|
# 3. Start using
|
|
dc3 device list
|
|
dc3 point read 456789
|
|
dc3 dashboard stats
|
|
```
|
|
|
|
## Commands
|
|
|
|
### Configuration (`dc3 config`)
|
|
|
|
```bash
|
|
dc3 config set gateway <url> # Set gateway URL
|
|
dc3 config set auth.tenant <tenant> # Set tenant code
|
|
dc3 config set auth.username <name> # Set username
|
|
dc3 config set auth.store <type> # Set credential store (keychain|encrypted|env|prompt)
|
|
dc3 config get <key> # Get config value
|
|
dc3 config list # List all profiles and settings
|
|
dc3 config profile use <name> # Switch profile
|
|
dc3 config reset # Reset all config
|
|
```
|
|
|
|
### Authentication (`dc3 auth`)
|
|
|
|
```bash
|
|
dc3 auth login # Interactive login
|
|
dc3 auth login --tenant default --username admin --password xxx # Non-interactive
|
|
dc3 auth login --store keychain # Save password to OS keychain
|
|
dc3 auth login --store encrypted # Save password to encrypted file
|
|
dc3 auth login --store env # Read password from DC3_PASSWORD env
|
|
dc3 auth login --no-save # Don't save password (manual re-login)
|
|
dc3 auth logout # Log out and invalidate token
|
|
dc3 auth status # Check auth status
|
|
dc3 auth token # Display current JWT token
|
|
dc3 auth token --header # Display full auth headers as JSON
|
|
```
|
|
|
|
### Device (`dc3 device`)
|
|
|
|
```bash
|
|
dc3 device list [--driver-id] [--profile-id] [--offset] [--limit]
|
|
dc3 device get <id>
|
|
dc3 device create --name "..." --driver-id "..." --profile-id "..."
|
|
dc3 device update <id> --version <n> [--name "..."] [--driver-id "..."] [--profile-id "..."]
|
|
dc3 device delete <id> --version <n>
|
|
dc3 device count --driver-id "..."
|
|
dc3 device status <id>
|
|
dc3 device import <file.xlsx> --driver-id "..." --profile-id "..." [--idempotency-key "..."] [--no-wait]
|
|
```
|
|
|
|
`device import` submits a canonical multipart request (`request` JSON part plus `file` XLSX part) with an idempotency key. It polls the returned durable operation until a terminal status by default; use `--no-wait` to return the `202 Accepted` resource immediately.
|
|
|
|
### Driver (`dc3 driver`)
|
|
|
|
```bash
|
|
dc3 driver list [--offset] [--limit]
|
|
dc3 driver get <id>
|
|
dc3 driver create --name "..." --service-name "..." --service-host "..." [--type DRIVER_CLIENT]
|
|
dc3 driver update <id> --version <n> [--name "..."] [--service-name "..."] [--service-host "..."]
|
|
dc3 driver delete <id> --version <n>
|
|
dc3 driver status <id>
|
|
```
|
|
|
|
### Point (`dc3 point`)
|
|
|
|
```bash
|
|
dc3 point list [--device-id] [--profile-id] [--offset] [--limit]
|
|
dc3 point get <id>
|
|
dc3 point read <id> # Read latest value
|
|
dc3 point history <id> --device-id <did> [--count 100] # Read history
|
|
dc3 point write <id> --device-id <did> --value 25.5 # Write value
|
|
dc3 point create --name "..." --profile-id "..." [--type FLOAT] [--rw READ_ONLY]
|
|
dc3 point update <id> --version <n> [--name "..."] [--profile-id "..."] [--type FLOAT]
|
|
dc3 point delete <id> --version <n>
|
|
```
|
|
|
|
### Profile (`dc3 profile`)
|
|
|
|
```bash
|
|
dc3 profile list [--device-id] [--type] [--offset] [--limit]
|
|
dc3 profile get <id>
|
|
dc3 profile create --name "..." [--type "..."]
|
|
dc3 profile update <id> --version <n> [--name "..."] [--type USER]
|
|
dc3 profile delete <id> --version <n>
|
|
```
|
|
|
|
### Group & Label (`dc3 group`, `dc3 label`)
|
|
|
|
```bash
|
|
dc3 group list [--offset] [--limit]
|
|
dc3 group get <id>
|
|
dc3 group create --name "..."
|
|
|
|
dc3 label list [--offset] [--limit]
|
|
dc3 label get <id>
|
|
```
|
|
|
|
### Event (`dc3 event`)
|
|
|
|
```bash
|
|
dc3 event list [--device-id] [--profile-id] [--offset] [--limit]
|
|
dc3 event get <id>
|
|
dc3 event create --name "..." --profile-id "..." [--type INFO] [--level LOW]
|
|
dc3 event update <id> --version <n> [--name "..."] [--profile-id "..."]
|
|
dc3 event delete <id> --version <n>
|
|
dc3 event history [--offset] [--limit]
|
|
```
|
|
|
|
### Command (`dc3 command`)
|
|
|
|
```bash
|
|
dc3 command list [--device-id] [--profile-id] [--offset] [--limit]
|
|
dc3 command get <id>
|
|
dc3 command create --name "..." --profile-id "..." [--type CUSTOM] [--call-type SYNC] [--timeout 30]
|
|
dc3 command update <id> --version <n> [--name "..."] [--profile-id "..."]
|
|
dc3 command delete <id> --version <n>
|
|
dc3 command call --device-id "..." --command-id "..." [--params '{"k":"v"}']
|
|
dc3 command history <recordId>
|
|
dc3 command history-list [--offset] [--limit]
|
|
```
|
|
|
|
### Alert (`dc3 alert`)
|
|
|
|
```bash
|
|
dc3 alert stats # Alert overview
|
|
dc3 alert list [--source device|driver|point] [--offset] [--limit]
|
|
dc3 alert latest [--limit 10] # Latest alerts
|
|
dc3 alert confirm --source device --id 789
|
|
dc3 alert unconfirm --source device --id 789
|
|
dc3 alert trend [--days 30] # Trend analysis
|
|
dc3 alert top-sources [--days 30] # Top alert sources
|
|
```
|
|
|
|
### Sessions & approvals (`dc3 session`, `dc3 action`)
|
|
|
|
Conversation lifecycle plus the high-risk tool-call approval loop:
|
|
|
|
```bash
|
|
dc3 session list
|
|
dc3 session messages conv-abc123
|
|
dc3 session rename conv-abc123 --name "boiler watch"
|
|
dc3 session delete conv-abc123
|
|
|
|
dc3 action pending --conversation-id conv-abc123 # offset page of tool calls awaiting approval
|
|
dc3 action pending --conversation-id conv-abc123 --offset 50 --limit 50
|
|
dc3 action confirm action-xyz789
|
|
dc3 action reject action-xyz789
|
|
```
|
|
|
|
### Analytics (`dc3 analytics`) — AI data-analysis surface
|
|
|
|
Nine coarse-grained statistical reads over point time series (S19 agent face); each op posts
|
|
one JSON body and returns a self-contained conclusion:
|
|
|
|
```bash
|
|
dc3 analytics list
|
|
dc3 analytics run query_history --args '{"pointId":456789,"days":7}'
|
|
dc3 analytics run trend_analysis --args '{"pointId":456789}'
|
|
```
|
|
|
|
### Alert deep analysis (`dc3 alert …`)
|
|
|
|
Beyond stats/list/confirm, the alert group exposes the diagnosis surface:
|
|
activity, storm-sources, flapping, correlation, peer-deviation, aging, mtta, change-impact,
|
|
latency (histogram), silent-sources, coverage-gap, and bulk-confirm. Generic flags:
|
|
|
|
```bash
|
|
dc3 alert aging --days 7
|
|
dc3 alert silent-sources --baseline-days 3 --limit 50
|
|
dc3 alert storm-sources --query source=device # extra k=v passthrough
|
|
dc3 alert bulk-confirm --args '{"items":[{"source":"device","id":789}]}'
|
|
```
|
|
|
|
### Dashboard (`dc3 dashboard`)
|
|
|
|
```bash
|
|
dc3 dashboard stats # Today statistics
|
|
dc3 dashboard timeseries [--granularity hour] [--range-hours 24]
|
|
dc3 dashboard top [--dimension device] [--range-hours 24] [--limit 10]
|
|
dc3 dashboard topology [--mode cardinality]
|
|
dc3 dashboard health # System + protocol health
|
|
dc3 dashboard stream [--limit 20] # Real-time data stream
|
|
dc3 dashboard driver-stats # Driver statistics
|
|
dc3 dashboard device-stats [--top-n 10]
|
|
```
|
|
|
|
### Topic (`dc3 topic`)
|
|
|
|
```bash
|
|
dc3 topic list [--offset] [--limit]
|
|
```
|
|
|
|
### Tool Catalog (`dc3 tools`)
|
|
|
|
MCP transport over the same OAuth ticket as REST (dual-transport design):
|
|
|
|
```bash
|
|
dc3 tools list # catalog visible to the ticket's scopes
|
|
dc3 tools call read_device --args '{"deviceId":456789}'
|
|
```
|
|
|
|
Requires `dc3 auth login --oauth`; classic login tickets are not accepted at `/mcp`.
|
|
|
|
### Chat — AI Agent (`dc3 chat`)
|
|
|
|
```bash
|
|
dc3 chat "检查1号设备的温度是否正常"
|
|
dc3 chat --model gpt-4o --stream "分析设备数据"
|
|
dc3 chat --conversation-id <id> # Continue conversation
|
|
```
|
|
|
|
## Global Options
|
|
|
|
| Option | Description |
|
|
| ---------------------------- | ----------------------------------------------------- |
|
|
| `--profile <name>` | Use a specific config profile |
|
|
| `--format json\|table\|yaml` | Output format (default: table for TTY, json for pipe) |
|
|
| `--verbose` | Show request/response details |
|
|
| `--ci` | CI mode: no colors, json output, strict exit codes |
|
|
|
|
## Multi-Profile
|
|
|
|
```bash
|
|
# Development
|
|
dc3 config profile use default
|
|
dc3 config set gateway http://localhost:8000
|
|
dc3 auth login
|
|
|
|
# Production
|
|
dc3 config profile use prod
|
|
dc3 config set gateway https://iot.example.com
|
|
dc3 auth login
|
|
|
|
# Switch
|
|
dc3 config profile use default
|
|
dc3 device list
|
|
```
|
|
|
|
## AI Agent Integration
|
|
|
|
### Via Shell (any AI coding tool)
|
|
|
|
```bash
|
|
# Claude Code / Codex / Gemini CLI / Hermes / OpenCode can run:
|
|
dc3 device list --format json
|
|
dc3 point read 456789 --format json
|
|
dc3 dashboard health --format json
|
|
```
|
|
|
|
### Via Gateway MCP (any MCP-compatible tool)
|
|
|
|
Configure your AI tool to connect to the Gateway MCP endpoint:
|
|
|
|
```jsonc
|
|
// Claude Code: .mcp.json
|
|
{
|
|
"mcpServers": {
|
|
"dc3": {
|
|
"transport": "http",
|
|
"url": "http://localhost:8000/mcp",
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
The AI agent will discover all platform API tools automatically.
|
|
|
|
## Credential Storage
|
|
|
|
| Store | Description | Use Case |
|
|
| ----------- | ------------------------------------------------------------------------------------ | ---------------------------------- |
|
|
| `keychain` | OS-level keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) | Daily use (default) |
|
|
| `encrypted` | AES-256-GCM encrypted file at `~/.dc3/credentials.enc` | Fallback when keychain unavailable |
|
|
| `env` | `DC3_PASSWORD` environment variable | CI/CD, scripting |
|
|
| `prompt` | Interactive prompt on every use | Maximum security, no auto-renewal |
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning |
|
|
| ---- | -------------------------------------------- |
|
|
| 0 | Success |
|
|
| 1 | Business error (invalid input, auth failure) |
|
|
| 2 | Network error (gateway unreachable) |
|
|
| 3 | Authentication error (needs login) |
|
|
|
|
## License
|
|
|
|
MIT
|