attune/docs/cli/cli.md

Attune CLI

The Attune CLI is a comprehensive command-line tool for interacting with the Attune automation platform. It provides an intuitive interface for managing all aspects of the platform including packs, actions, rules, executions, and more.

Overview

The CLI is designed to be:

• Intuitive: Natural command structure with helpful prompts
• Flexible: Multiple output formats for human and machine consumption
• Powerful: Full access to all API functionality
• Scriptable: JSON/YAML output for automation

Installation

From Source

cd attune
cargo install --path crates/cli

This will install the attune binary to your cargo bin directory (usually ~/.cargo/bin).

Development

cargo build -p attune-cli
./target/debug/attune --help

Configuration

The CLI stores configuration in ~/.config/attune/config.yaml (respects $XDG_CONFIG_HOME).

Configuration Structure

api_url: http://localhost:8080
auth_token: <jwt-access-token>
refresh_token: <jwt-refresh-token>
output_format: table

Environment Variables

• ATTUNE_API_URL: Override the API endpoint
• XDG_CONFIG_HOME: Change config directory location

Global Options

All commands support:

• --api-url <URL>: Override API endpoint
• --output <format>: Set 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 debug logging

Command Reference

Authentication

Login

attune auth login --username admin
# Prompts for password securely

Logout

attune auth logout

Check Current User

attune auth whoami

Pack Management

List Packs

attune pack list
attune pack list --name core
attune pack list --output json  # Long form
attune pack list -j             # Shorthand for JSON
attune pack list -y             # Shorthand for YAML

Show Pack Details

attune pack show core
attune pack show 1

Install Pack

attune pack install https://github.com/example/pack-example
attune pack install https://github.com/example/pack-example --ref v1.0.0
attune pack install <url> --force

Register Local Pack

attune pack register /path/to/pack

Uninstall Pack

attune pack uninstall core
attune pack uninstall core --yes

Action Management

List Actions

attune action list
attune action list --pack core
attune action list --name echo

Show Action Details

attune action show core.echo
attune action show 1

Execute Action

# With key=value parameters
attune action execute core.echo --param message="Hello" --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 timeout
attune action execute core.long_task --wait --timeout 600

Rule Management

List Rules

attune rule list
attune rule list --pack core
attune rule list --enabled true

Show Rule Details

attune rule show core.on_webhook
attune rule show 1

Enable/Disable Rules

attune rule enable core.on_webhook
attune rule disable core.on_webhook

Create Rule

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 '{"event.payload.severity": "critical"}'

Delete Rule

attune rule delete core.my_rule
attune rule delete core.my_rule --yes

Execution Monitoring

List Executions

attune execution list
attune execution list --pack core
attune execution list --action core.echo
attune execution list --status succeeded
attune execution list --result "error"
attune execution list --pack monitoring --status failed --result "timeout"
attune execution list --limit 100

Show Execution Details

attune execution show 123

View Logs

attune execution logs 123
attune execution logs 123 --follow

Cancel Execution

attune execution cancel 123
attune execution cancel 123 --yes

Get Raw Execution Result

# 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

attune trigger list
attune trigger list --pack core

Show Trigger Details

attune trigger show core.webhook

Sensor Management

List Sensors

attune sensor list
attune sensor list --pack core

Show Sensor Details

attune sensor show core.file_watcher

Configuration Management

List Configuration

attune config list

Get Value

attune config get api_url

Set Value

attune config set api_url https://attune.example.com
attune config set output_format json

Show Config Path

attune config path

Output Formats

Table (Default)

Human-readable format with colors and formatting:

attune pack list

Output:

╭────┬──────┬─────────┬─────────┬─────────────────╮
│ ID │ Name │ Version │ Enabled │ Description     │
├────┼──────┼─────────┼─────────┼─────────────────┤
│ 1  │ core │ 1.0.0   │ ✓       │ Core actions... │
╰────┴──────┴─────────┴─────────┴─────────────────╯

JSON

Machine-readable format for scripting:

attune pack list --output json  # Long form
attune pack list -j             # Shorthand

Output:

[
  {
    "id": 1,
    "name": "core",
    "version": "1.0.0",
    "enabled": true,
    "description": "Core actions..."
  }
]

YAML

Alternative structured format:

attune pack list --output yaml  # Long form
attune pack list -y             # Shorthand

Output:

- id: 1
  name: core
  version: 1.0.0
  enabled: true
  description: Core actions...

Scripting Examples

Bash Script: Deploy Pack

#!/bin/bash
set -e

PACK_URL="https://github.com/example/monitoring-pack"
PACK_NAME="monitoring"

# Install pack
echo "Installing pack..."
PACK_ID=$(attune pack install "$PACK_URL" -j | jq -r '.id')

# Verify installation
if [ -z "$PACK_ID" ]; then
  echo "Pack installation failed"
  exit 1
fi

echo "Pack installed: ID=$PACK_ID"

# Enable all rules
attune rule list --pack "$PACK_NAME" -j | \
  jq -r '.[].id' | \
  xargs -I {} attune rule enable {}

echo "All rules enabled"

Bash Script: Process Execution Results

#!/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[]'

Python Script: Monitor Executions

#!/usr/bin/env python3
import json
import subprocess
import time

def get_executions(status=None, pack=None, result_contains=None, limit=10):
    cmd = ["attune", "execution", "list", "-j", f"--limit={limit}"]
    if status:
        cmd.extend(["--status", status])
    if pack:
        cmd.extend(["--pack", pack])
    if result_contains:
        cmd.extend(["--result", result_contains])
    
    result = subprocess.run(cmd, capture_output=True, text=True)
    return json.loads(result.stdout)

def main():
    print("Monitoring failed executions with errors...")
    while True:
        # Find failed executions containing "error" in result
        failed = get_executions(status="failed", result_contains="error", limit=5)
        if failed:
            print(f"Found {len(failed)} failed executions:")
            for exec in failed:
                print(f"  - ID {exec['id']}: {exec['action_name']}")
        time.sleep(30)

if __name__ == "__main__":
    main()

Troubleshooting

Authentication Issues

Problem: "Not logged in" error

Solution:

# Check auth status
attune auth whoami

# Login again
attune auth login --username admin

Connection Issues

Problem: Cannot connect to API

Solution:

# Check API URL
attune config get api_url

# Override temporarily
attune --api-url http://localhost:8080 auth whoami

# Update permanently
attune config set api_url http://localhost:8080

Token Expiration

Problem: "Invalid token" error

Solution:

# Login again to refresh token
attune auth login --username admin

Verbose Debugging

Enable verbose output to see HTTP requests:

attune --verbose pack list

Best Practices

Security

1. Never hardcode passwords: Use interactive prompts
2. Protect config file: Contains JWT tokens
3. Use environment variables for CI/CD: ATTUNE_API_URL

Scripting

1. Use JSON output for parsing: --output json
2. Check exit codes: Non-zero on error
3. Handle errors: Use set -e in bash scripts
4. Use jq for JSON processing

Performance

1. Limit results: Use --limit for large lists
2. Filter server-side: Use --pack, --action, --status, --result filters
3. Avoid polling: Use --wait for action execution
4. Use specific filters: Narrow results with combined filters for faster queries

Architecture

Components

attune-cli/
├── src/
│   ├── main.rs           # Entry point, CLI structure
│   ├── client.rs         # HTTP client wrapper
│   ├── config.rs         # Config file management
│   ├── output.rs         # Output formatting
│   └── commands/         # Command implementations
│       ├── auth.rs
│       ├── pack.rs
│       ├── action.rs
│       ├── rule.rs
│       ├── execution.rs
│       ├── trigger.rs
│       ├── sensor.rs
│       └── config.rs

Key Dependencies

• clap: CLI argument parsing
• reqwest: HTTP client
• serde_json/yaml: Serialization
• colored: Terminal colors
• comfy-table: Table formatting
• dialoguer: Interactive prompts

API Communication

The CLI communicates with the Attune API using:

• REST endpoints at /api/v1/*
• JWT bearer token authentication
• Standard JSON request/response format

Future Enhancements

Potential future features:

• Shell completion (bash, zsh, fish)
• Interactive TUI mode
• Execution streaming (real-time logs)
• Bulk operations
• Pack development commands
• Workflow visualization
• Config profiles (dev, staging, prod)

Related Documentation

• Main README
• API Documentation
• Pack Development
• Configuration Guide