591 lines
11 KiB
Markdown
591 lines
11 KiB
Markdown
# Attune CLI
|
|
|
|
The Attune CLI is a command-line interface for interacting with the Attune automation platform. It provides an intuitive and flexible interface for managing packs, actions, rules, sensors, triggers, and executions.
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
cargo install --path crates/cli
|
|
```
|
|
|
|
The binary will be named `attune`.
|
|
|
|
### Development Build
|
|
|
|
```bash
|
|
cargo build -p attune-cli
|
|
./target/debug/attune --help
|
|
```
|
|
|
|
### Release Build
|
|
|
|
```bash
|
|
cargo build -p attune-cli --release
|
|
./target/release/attune --help
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The CLI stores configuration in `~/.config/attune/config.yaml` (or `$XDG_CONFIG_HOME/attune/config.yaml`).
|
|
|
|
Default configuration:
|
|
```yaml
|
|
api_url: http://localhost:8080
|
|
auth_token: null
|
|
refresh_token: null
|
|
output_format: table
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
- `ATTUNE_API_URL`: Override the API endpoint URL
|
|
- Standard XDG environment variables for config directory location
|
|
|
|
### Global Flags
|
|
|
|
All commands support these global flags:
|
|
|
|
- `--api-url <URL>`: Override the API endpoint (also via `ATTUNE_API_URL`)
|
|
- `--output <FORMAT>`: Output format (`table`, `json`, `yaml`)
|
|
- `-j, --json`: Output as JSON (shorthand for `--output json`)
|
|
- `-y, --yaml`: Output as YAML (shorthand for `--output yaml`)
|
|
- `-v, --verbose`: Enable verbose logging
|
|
|
|
## Authentication
|
|
|
|
### Login
|
|
|
|
```bash
|
|
# Interactive password prompt
|
|
attune auth login --username admin
|
|
|
|
# With password (not recommended for interactive use)
|
|
attune auth login --username admin --password secret
|
|
|
|
# With custom API URL
|
|
attune auth login --username admin --api-url https://attune.example.com
|
|
```
|
|
|
|
### Logout
|
|
|
|
```bash
|
|
attune auth logout
|
|
```
|
|
|
|
### Check Current User
|
|
|
|
```bash
|
|
attune auth whoami
|
|
```
|
|
|
|
## Pack Management
|
|
|
|
### List Packs
|
|
|
|
```bash
|
|
# List all packs
|
|
attune pack list
|
|
|
|
# Filter by name
|
|
attune pack list --name core
|
|
|
|
# JSON output (long form)
|
|
attune pack list --output json
|
|
|
|
# JSON output (shorthand)
|
|
attune pack list -j
|
|
|
|
# YAML output (shorthand)
|
|
attune pack list -y
|
|
```
|
|
|
|
### Show Pack Details
|
|
|
|
```bash
|
|
# By name
|
|
attune pack show core
|
|
|
|
# By ID
|
|
attune pack show 1
|
|
```
|
|
|
|
### Install Pack
|
|
|
|
```bash
|
|
# From git repository
|
|
attune pack install https://github.com/example/attune-pack-example
|
|
|
|
# From git with specific branch/tag
|
|
attune pack install https://github.com/example/attune-pack-example --ref v1.0.0
|
|
|
|
# Force reinstall
|
|
attune pack install https://github.com/example/attune-pack-example --force
|
|
```
|
|
|
|
### Register Local Pack
|
|
|
|
```bash
|
|
# Register from local directory
|
|
attune pack register /path/to/pack
|
|
```
|
|
|
|
### Uninstall Pack
|
|
|
|
```bash
|
|
# Interactive confirmation
|
|
attune pack uninstall core
|
|
|
|
# Skip confirmation
|
|
attune pack uninstall core --yes
|
|
```
|
|
|
|
## Action Management
|
|
|
|
### List Actions
|
|
|
|
```bash
|
|
# List all actions
|
|
attune action list
|
|
|
|
# Filter by pack
|
|
attune action list --pack core
|
|
|
|
# Filter by name
|
|
attune action list --name execute
|
|
```
|
|
|
|
### Show Action Details
|
|
|
|
```bash
|
|
# By pack.action reference
|
|
attune action show core.echo
|
|
|
|
# By ID
|
|
attune action show 1
|
|
```
|
|
|
|
### Execute Action
|
|
|
|
```bash
|
|
# With key=value parameters
|
|
attune action execute core.echo --param message="Hello World" --param count=3
|
|
|
|
# With JSON parameters
|
|
attune action execute core.echo --params-json '{"message": "Hello", "count": 5}'
|
|
|
|
# Wait for completion
|
|
attune action execute core.long_task --wait
|
|
|
|
# Wait with custom timeout (default 300 seconds)
|
|
attune action execute core.long_task --wait --timeout 600
|
|
```
|
|
|
|
## Rule Management
|
|
|
|
### List Rules
|
|
|
|
```bash
|
|
# List all rules
|
|
attune rule list
|
|
|
|
# Filter by pack
|
|
attune rule list --pack core
|
|
|
|
# Filter by enabled status
|
|
attune rule list --enabled true
|
|
```
|
|
|
|
### Show Rule Details
|
|
|
|
```bash
|
|
# By pack.rule reference
|
|
attune rule show core.on_webhook
|
|
|
|
# By ID
|
|
attune rule show 1
|
|
```
|
|
|
|
### Enable/Disable Rules
|
|
|
|
```bash
|
|
# Enable a rule
|
|
attune rule enable core.on_webhook
|
|
|
|
# Disable a rule
|
|
attune rule disable core.on_webhook
|
|
```
|
|
|
|
### Create Rule
|
|
|
|
```bash
|
|
attune rule create \
|
|
--name my_rule \
|
|
--pack core \
|
|
--trigger core.webhook \
|
|
--action core.notify \
|
|
--description "Notify on webhook" \
|
|
--enabled
|
|
|
|
# With criteria
|
|
attune rule create \
|
|
--name filtered_rule \
|
|
--pack core \
|
|
--trigger core.webhook \
|
|
--action core.notify \
|
|
--criteria '{"trigger.payload.severity": "critical"}'
|
|
```
|
|
|
|
### Delete Rule
|
|
|
|
```bash
|
|
# Interactive confirmation
|
|
attune rule delete core.my_rule
|
|
|
|
# Skip confirmation
|
|
attune rule delete core.my_rule --yes
|
|
```
|
|
|
|
## Execution Monitoring
|
|
|
|
### List Executions
|
|
|
|
```bash
|
|
# List recent executions (default: last 50)
|
|
attune execution list
|
|
|
|
# Filter by pack
|
|
attune execution list --pack core
|
|
|
|
# Filter by action
|
|
attune execution list --action core.echo
|
|
|
|
# Filter by status
|
|
attune execution list --status succeeded
|
|
|
|
# Search in execution results
|
|
attune execution list --result "error"
|
|
|
|
# Combine filters
|
|
attune execution list --pack monitoring --status failed --result "timeout"
|
|
|
|
# Limit results
|
|
attune execution list --limit 100
|
|
```
|
|
|
|
### Show Execution Details
|
|
|
|
```bash
|
|
attune execution show 123
|
|
```
|
|
|
|
### View Execution Logs
|
|
|
|
```bash
|
|
# Show logs
|
|
attune execution logs 123
|
|
|
|
# Follow logs (real-time)
|
|
attune execution logs 123 --follow
|
|
```
|
|
|
|
### Cancel Execution
|
|
|
|
```bash
|
|
# Interactive confirmation
|
|
attune execution cancel 123
|
|
|
|
# Skip confirmation
|
|
attune execution cancel 123 --yes
|
|
```
|
|
|
|
### Get Raw Execution Result
|
|
|
|
Get just the result data from a completed execution, useful for piping to other tools.
|
|
|
|
```bash
|
|
# Get result as JSON (default)
|
|
attune execution result 123
|
|
|
|
# Get result as YAML
|
|
attune execution result 123 --format yaml
|
|
|
|
# Pipe to jq for processing
|
|
attune execution result 123 | jq '.data.field'
|
|
|
|
# Extract specific field
|
|
attune execution result 123 | jq -r '.status'
|
|
```
|
|
|
|
## Trigger Management
|
|
|
|
### List Triggers
|
|
|
|
```bash
|
|
# List all triggers
|
|
attune trigger list
|
|
|
|
# Filter by pack
|
|
attune trigger list --pack core
|
|
```
|
|
|
|
### Show Trigger Details
|
|
|
|
```bash
|
|
attune trigger show core.webhook
|
|
```
|
|
|
|
## Sensor Management
|
|
|
|
### List Sensors
|
|
|
|
```bash
|
|
# List all sensors
|
|
attune sensor list
|
|
|
|
# Filter by pack
|
|
attune sensor list --pack core
|
|
```
|
|
|
|
### Show Sensor Details
|
|
|
|
```bash
|
|
attune sensor show core.file_watcher
|
|
```
|
|
|
|
## CLI Configuration
|
|
|
|
### List Configuration
|
|
|
|
```bash
|
|
attune config list
|
|
```
|
|
|
|
### Get Configuration Value
|
|
|
|
```bash
|
|
attune config get api_url
|
|
```
|
|
|
|
### Set Configuration Value
|
|
|
|
```bash
|
|
# Set API URL
|
|
attune config set api_url https://attune.example.com
|
|
|
|
# Set output format
|
|
attune config set output_format json
|
|
```
|
|
|
|
### Show Configuration File Path
|
|
|
|
```bash
|
|
attune config path
|
|
```
|
|
|
|
## Output Formats
|
|
|
|
### Table (Default)
|
|
|
|
Human-readable table format with colored output:
|
|
|
|
```bash
|
|
attune pack list
|
|
```
|
|
|
|
### JSON
|
|
|
|
Machine-readable JSON for scripting:
|
|
|
|
```bash
|
|
# Long form
|
|
attune pack list --output json
|
|
|
|
# Shorthand
|
|
attune pack list -j
|
|
```
|
|
|
|
### YAML
|
|
|
|
YAML format:
|
|
|
|
```bash
|
|
# Long form
|
|
attune pack list --output yaml
|
|
|
|
# Shorthand
|
|
attune pack list -y
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Complete Workflow Example
|
|
|
|
```bash
|
|
# 1. Login
|
|
attune auth login --username admin
|
|
|
|
# 2. Install a pack
|
|
attune pack install https://github.com/example/monitoring-pack
|
|
|
|
# 3. List available actions
|
|
attune action list --pack monitoring
|
|
|
|
# 4. Execute an action
|
|
attune action execute monitoring.check_health --param endpoint=https://api.example.com
|
|
|
|
# 5. Enable a rule
|
|
attune rule enable monitoring.alert_on_failure
|
|
|
|
# 6. Monitor executions
|
|
attune execution list --action monitoring.check_health
|
|
```
|
|
|
|
### Scripting Example
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Deploy and test a pack
|
|
|
|
set -e
|
|
|
|
PACK_URL="https://github.com/example/my-pack"
|
|
PACK_NAME="my-pack"
|
|
|
|
# Install pack
|
|
echo "Installing pack..."
|
|
attune pack install "$PACK_URL" -j | jq -r '.id'
|
|
|
|
# Verify installation
|
|
echo "Verifying pack..."
|
|
PACK_ID=$(attune pack list --name "$PACK_NAME" -j | jq -r '.[0].id')
|
|
|
|
if [ -z "$PACK_ID" ]; then
|
|
echo "Pack installation failed"
|
|
exit 1
|
|
fi
|
|
|
|
echo "Pack installed successfully with ID: $PACK_ID"
|
|
|
|
# List actions in the pack
|
|
echo "Actions in pack:"
|
|
attune action list --pack "$PACK_NAME"
|
|
|
|
# Enable all rules in the pack
|
|
attune rule list --pack "$PACK_NAME" -j | \
|
|
jq -r '.[].id' | \
|
|
xargs -I {} attune rule enable {}
|
|
|
|
echo "All rules enabled"
|
|
```
|
|
|
|
### Process Execution Results
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Extract and process execution results
|
|
|
|
EXECUTION_ID=123
|
|
|
|
# Get raw result
|
|
RESULT=$(attune execution result $EXECUTION_ID)
|
|
|
|
# Extract specific fields
|
|
STATUS=$(echo "$RESULT" | jq -r '.status')
|
|
MESSAGE=$(echo "$RESULT" | jq -r '.message')
|
|
|
|
echo "Status: $STATUS"
|
|
echo "Message: $MESSAGE"
|
|
|
|
# Or pipe directly
|
|
attune execution result $EXECUTION_ID | jq -r '.errors[]'
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Authentication Issues
|
|
|
|
If you get authentication errors:
|
|
|
|
1. Check you're logged in: `attune auth whoami`
|
|
2. Try logging in again: `attune auth login --username <user>`
|
|
3. Verify API URL: `attune config get api_url`
|
|
|
|
### Connection Issues
|
|
|
|
If you can't connect to the API:
|
|
|
|
1. Verify the API is running: `curl http://localhost:8080/health`
|
|
2. Check the configured URL: `attune config get api_url`
|
|
3. Override the URL: `attune --api-url http://localhost:8080 auth whoami`
|
|
|
|
### Verbose Logging
|
|
|
|
Enable verbose logging for debugging:
|
|
|
|
```bash
|
|
attune --verbose pack list
|
|
```
|
|
|
|
## Development
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cargo build -p attune-cli
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
cargo test -p attune-cli
|
|
```
|
|
|
|
### Code Structure
|
|
|
|
```
|
|
crates/cli/
|
|
├── src/
|
|
│ ├── main.rs # Entry point and CLI structure
|
|
│ ├── client.rs # HTTP client for API calls
|
|
│ ├── config.rs # Configuration management
|
|
│ ├── output.rs # Output formatting (table, JSON, YAML)
|
|
│ └── commands/ # Command implementations
|
|
│ ├── auth.rs # Authentication commands
|
|
│ ├── pack.rs # Pack management commands
|
|
│ ├── action.rs # Action commands
|
|
│ ├── rule.rs # Rule commands
|
|
│ ├── execution.rs # Execution commands
|
|
│ ├── trigger.rs # Trigger commands
|
|
│ ├── sensor.rs # Sensor commands
|
|
│ └── config.rs # Config commands
|
|
└── Cargo.toml
|
|
```
|
|
|
|
## Features
|
|
|
|
- ✅ JWT authentication with token storage
|
|
- ✅ Multiple output formats (table, JSON, YAML)
|
|
- ✅ Colored and formatted table output
|
|
- ✅ Interactive prompts for sensitive operations
|
|
- ✅ Configuration management
|
|
- ✅ Advanced execution search (by pack, action, status, result content)
|
|
- ✅ Comprehensive pack management
|
|
- ✅ Action execution with parameter support
|
|
- ✅ Rule creation and management
|
|
- ✅ Execution monitoring and logs with advanced filtering
|
|
- ✅ Raw result extraction for piping to other tools
|
|
- ✅ Shorthand output flags (`-j`, `-y`) for CLI convenience
|
|
- ✅ Environment variable overrides
|
|
|
|
## Dependencies
|
|
|
|
Key dependencies:
|
|
- `clap`: CLI argument parsing
|
|
- `reqwest`: HTTP client
|
|
- `serde_json` / `serde_yaml`: Serialization
|
|
- `colored`: Terminal colors
|
|
- `comfy-table`: Table formatting
|
|
- `dialoguer`: Interactive prompts
|
|
- `indicatif`: Progress indicators (for future use) |