working out the worker/execution interface
This commit is contained in:
473
docs/cli-pack-installation.md
Normal file
473
docs/cli-pack-installation.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# CLI Pack Installation Quick Reference
|
||||
|
||||
This document provides quick reference commands for installing, managing, and working with packs using the Attune CLI.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Installation Commands](#installation-commands)
|
||||
- [Using Actions Directly](#using-actions-directly)
|
||||
- [Using the Workflow](#using-the-workflow)
|
||||
- [Management Commands](#management-commands)
|
||||
- [Examples](#examples)
|
||||
|
||||
## Installation Commands
|
||||
|
||||
### Install Pack from Source
|
||||
|
||||
Install a pack from git, HTTP, or registry:
|
||||
|
||||
```bash
|
||||
# From git repository (HTTPS)
|
||||
attune pack install https://github.com/attune/pack-slack.git
|
||||
|
||||
# From git repository with specific ref
|
||||
attune pack install https://github.com/attune/pack-slack.git --ref-spec v1.0.0
|
||||
|
||||
# From git repository (SSH)
|
||||
attune pack install git@github.com:attune/pack-slack.git
|
||||
|
||||
# From HTTP archive
|
||||
attune pack install https://example.com/packs/slack-1.0.0.tar.gz
|
||||
|
||||
# From registry (if configured)
|
||||
attune pack install slack@1.0.0
|
||||
|
||||
# With options
|
||||
attune pack install slack@1.0.0 \
|
||||
--force \
|
||||
--skip-tests \
|
||||
--skip-deps
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--ref-spec <REF>` - Git branch, tag, or commit
|
||||
- `--force` - Force reinstall if pack exists
|
||||
- `--skip-tests` - Skip running pack tests
|
||||
- `--skip-deps` - Skip dependency validation
|
||||
- `--no-registry` - Don't use registry for resolution
|
||||
|
||||
### Register Pack from Local Path
|
||||
|
||||
Register a pack that's already on disk:
|
||||
|
||||
```bash
|
||||
# Register pack from directory
|
||||
attune pack register /path/to/pack
|
||||
|
||||
# With options
|
||||
attune pack register /path/to/pack \
|
||||
--force \
|
||||
--skip-tests
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--force` - Replace existing pack
|
||||
- `--skip-tests` - Skip running pack tests
|
||||
|
||||
## Using Actions Directly
|
||||
|
||||
The pack installation workflow consists of individual actions that can be run separately:
|
||||
|
||||
### 1. Download Packs
|
||||
|
||||
```bash
|
||||
# Download one or more packs
|
||||
attune action execute core.download_packs \
|
||||
--param packs='["https://github.com/attune/pack-slack.git"]' \
|
||||
--param destination_dir=/tmp/attune-packs \
|
||||
--wait
|
||||
|
||||
# Multiple packs
|
||||
attune action execute core.download_packs \
|
||||
--param packs='["slack@1.0.0","aws@2.0.0"]' \
|
||||
--param destination_dir=/tmp/attune-packs \
|
||||
--param registry_url=https://registry.attune.io/index.json \
|
||||
--wait
|
||||
|
||||
# Get JSON output
|
||||
attune action execute core.download_packs \
|
||||
--param packs='["https://github.com/attune/pack-slack.git"]' \
|
||||
--param destination_dir=/tmp/attune-packs \
|
||||
--wait --json
|
||||
```
|
||||
|
||||
### 2. Get Pack Dependencies
|
||||
|
||||
```bash
|
||||
# Analyze pack dependencies
|
||||
attune action execute core.get_pack_dependencies \
|
||||
--param pack_paths='["/tmp/attune-packs/slack"]' \
|
||||
--wait
|
||||
|
||||
# With JSON output to check for missing dependencies
|
||||
result=$(attune action execute core.get_pack_dependencies \
|
||||
--param pack_paths='["/tmp/attune-packs/slack"]' \
|
||||
--wait --json)
|
||||
|
||||
echo "$result" | jq '.result.missing_dependencies'
|
||||
```
|
||||
|
||||
### 3. Build Pack Environments
|
||||
|
||||
```bash
|
||||
# Build Python and Node.js environments
|
||||
attune action execute core.build_pack_envs \
|
||||
--param pack_paths='["/tmp/attune-packs/slack"]' \
|
||||
--wait
|
||||
|
||||
# Skip Node.js environment
|
||||
attune action execute core.build_pack_envs \
|
||||
--param pack_paths='["/tmp/attune-packs/slack"]' \
|
||||
--param skip_nodejs=true \
|
||||
--wait
|
||||
|
||||
# Force rebuild
|
||||
attune action execute core.build_pack_envs \
|
||||
--param pack_paths='["/tmp/attune-packs/slack"]' \
|
||||
--param force_rebuild=true \
|
||||
--wait
|
||||
```
|
||||
|
||||
### 4. Register Packs
|
||||
|
||||
```bash
|
||||
# Register downloaded packs
|
||||
attune action execute core.register_packs \
|
||||
--param pack_paths='["/tmp/attune-packs/slack"]' \
|
||||
--wait
|
||||
|
||||
# With force and skip tests
|
||||
attune action execute core.register_packs \
|
||||
--param pack_paths='["/tmp/attune-packs/slack"]' \
|
||||
--param force=true \
|
||||
--param skip_tests=true \
|
||||
--wait
|
||||
```
|
||||
|
||||
## Using the Workflow
|
||||
|
||||
The `core.install_packs` workflow automates the entire process:
|
||||
|
||||
```bash
|
||||
# Install pack using workflow
|
||||
attune action execute core.install_packs \
|
||||
--param packs='["https://github.com/attune/pack-slack.git"]' \
|
||||
--wait
|
||||
|
||||
# With options
|
||||
attune action execute core.install_packs \
|
||||
--param packs='["slack@1.0.0","aws@2.0.0"]' \
|
||||
--param force=true \
|
||||
--param skip_tests=true \
|
||||
--wait
|
||||
|
||||
# Install with specific git ref
|
||||
attune action execute core.install_packs \
|
||||
--param packs='["https://github.com/attune/pack-slack.git"]' \
|
||||
--param ref_spec=v1.0.0 \
|
||||
--wait
|
||||
```
|
||||
|
||||
**Note**: When the workflow feature is fully implemented, use:
|
||||
```bash
|
||||
attune workflow execute core.install_packs \
|
||||
--input packs='["slack@1.0.0"]'
|
||||
```
|
||||
|
||||
## Management Commands
|
||||
|
||||
### List Packs
|
||||
|
||||
```bash
|
||||
# List all installed packs
|
||||
attune pack list
|
||||
|
||||
# Filter by name
|
||||
attune pack list --name slack
|
||||
|
||||
# JSON output
|
||||
attune pack list --json
|
||||
```
|
||||
|
||||
### Show Pack Details
|
||||
|
||||
```bash
|
||||
# Show pack information
|
||||
attune pack show slack
|
||||
|
||||
# JSON output
|
||||
attune pack show slack --json
|
||||
```
|
||||
|
||||
### Update Pack Metadata
|
||||
|
||||
```bash
|
||||
# Update pack fields
|
||||
attune pack update slack \
|
||||
--label "Slack Integration" \
|
||||
--description "Enhanced Slack pack" \
|
||||
--version 1.1.0
|
||||
```
|
||||
|
||||
### Uninstall Pack
|
||||
|
||||
```bash
|
||||
# Uninstall pack (with confirmation)
|
||||
attune pack uninstall slack
|
||||
|
||||
# Force uninstall without confirmation
|
||||
attune pack uninstall slack --yes
|
||||
```
|
||||
|
||||
### Test Pack
|
||||
|
||||
```bash
|
||||
# Run pack tests
|
||||
attune pack test slack
|
||||
|
||||
# Verbose output
|
||||
attune pack test slack --verbose
|
||||
|
||||
# Detailed output
|
||||
attune pack test slack --detailed
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Install Pack from Git
|
||||
|
||||
```bash
|
||||
# Full installation process
|
||||
attune pack install https://github.com/attune/pack-slack.git --ref-spec v1.0.0 --wait
|
||||
|
||||
# Verify installation
|
||||
attune pack show slack
|
||||
|
||||
# List actions in pack
|
||||
attune action list --pack slack
|
||||
```
|
||||
|
||||
### Example 2: Install Multiple Packs
|
||||
|
||||
```bash
|
||||
# Install multiple packs from registry
|
||||
attune action execute core.install_packs \
|
||||
--param packs='["slack@1.0.0","aws@2.1.0","kubernetes@3.0.0"]' \
|
||||
--wait
|
||||
```
|
||||
|
||||
### Example 3: Development Workflow
|
||||
|
||||
```bash
|
||||
# Download pack for development
|
||||
attune action execute core.download_packs \
|
||||
--param packs='["https://github.com/myorg/pack-custom.git"]' \
|
||||
--param destination_dir=/home/user/packs \
|
||||
--param ref_spec=main \
|
||||
--wait
|
||||
|
||||
# Make changes to pack...
|
||||
|
||||
# Register updated pack
|
||||
attune pack register /home/user/packs/custom --force
|
||||
```
|
||||
|
||||
### Example 4: Check Dependencies Before Install
|
||||
|
||||
```bash
|
||||
# Download pack
|
||||
attune action execute core.download_packs \
|
||||
--param packs='["slack@1.0.0"]' \
|
||||
--param destination_dir=/tmp/test-pack \
|
||||
--wait
|
||||
|
||||
# Check dependencies
|
||||
deps=$(attune action execute core.get_pack_dependencies \
|
||||
--param pack_paths='["/tmp/test-pack/slack"]' \
|
||||
--wait --json)
|
||||
|
||||
# Check for missing dependencies
|
||||
missing=$(echo "$deps" | jq -r '.result.missing_dependencies | length')
|
||||
|
||||
if [[ "$missing" -gt 0 ]]; then
|
||||
echo "Missing dependencies found:"
|
||||
echo "$deps" | jq '.result.missing_dependencies'
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Proceed with installation
|
||||
attune pack register /tmp/test-pack/slack
|
||||
```
|
||||
|
||||
### Example 5: Scripted Installation with Error Handling
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
PACK_SOURCE="https://github.com/attune/pack-slack.git"
|
||||
PACK_REF="v1.0.0"
|
||||
TEMP_DIR="/tmp/attune-install-$$"
|
||||
|
||||
echo "Installing pack from: $PACK_SOURCE"
|
||||
|
||||
# Download
|
||||
echo "Step 1: Downloading..."
|
||||
download_result=$(attune action execute core.download_packs \
|
||||
--param packs="[\"$PACK_SOURCE\"]" \
|
||||
--param destination_dir="$TEMP_DIR" \
|
||||
--param ref_spec="$PACK_REF" \
|
||||
--wait --json)
|
||||
|
||||
success=$(echo "$download_result" | jq -r '.result.success_count // 0')
|
||||
if [[ "$success" -eq 0 ]]; then
|
||||
echo "Error: Download failed"
|
||||
echo "$download_result" | jq '.result.failed_packs'
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Get pack path
|
||||
pack_path=$(echo "$download_result" | jq -r '.result.downloaded_packs[0].pack_path')
|
||||
echo "Downloaded to: $pack_path"
|
||||
|
||||
# Check dependencies
|
||||
echo "Step 2: Checking dependencies..."
|
||||
deps_result=$(attune action execute core.get_pack_dependencies \
|
||||
--param pack_paths="[\"$pack_path\"]" \
|
||||
--wait --json)
|
||||
|
||||
missing=$(echo "$deps_result" | jq -r '.result.missing_dependencies | length')
|
||||
if [[ "$missing" -gt 0 ]]; then
|
||||
echo "Warning: Missing dependencies:"
|
||||
echo "$deps_result" | jq '.result.missing_dependencies'
|
||||
fi
|
||||
|
||||
# Build environments
|
||||
echo "Step 3: Building environments..."
|
||||
attune action execute core.build_pack_envs \
|
||||
--param pack_paths="[\"$pack_path\"]" \
|
||||
--wait
|
||||
|
||||
# Register
|
||||
echo "Step 4: Registering pack..."
|
||||
attune pack register "$pack_path"
|
||||
|
||||
# Cleanup
|
||||
rm -rf "$TEMP_DIR"
|
||||
|
||||
echo "Installation complete!"
|
||||
```
|
||||
|
||||
### Example 6: Bulk Pack Installation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Install multiple packs from a list
|
||||
|
||||
PACKS=(
|
||||
"slack@1.0.0"
|
||||
"aws@2.1.0"
|
||||
"kubernetes@3.0.0"
|
||||
"datadog@1.5.0"
|
||||
)
|
||||
|
||||
for pack in "${PACKS[@]}"; do
|
||||
echo "Installing: $pack"
|
||||
if attune pack install "$pack" --skip-tests; then
|
||||
echo "✓ $pack installed successfully"
|
||||
else
|
||||
echo "✗ $pack installation failed"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
All commands support multiple output formats:
|
||||
|
||||
```bash
|
||||
# Default table format
|
||||
attune pack list
|
||||
|
||||
# JSON format
|
||||
attune pack list --json
|
||||
attune pack list -j
|
||||
|
||||
# YAML format
|
||||
attune pack list --yaml
|
||||
attune pack list -y
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
Most commands require authentication:
|
||||
|
||||
```bash
|
||||
# Login first
|
||||
attune auth login
|
||||
|
||||
# Or use a token
|
||||
export ATTUNE_API_TOKEN="your-token-here"
|
||||
attune pack list
|
||||
|
||||
# Or specify token in command
|
||||
attune pack list --api-url http://localhost:8080
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Configure CLI settings:
|
||||
|
||||
```bash
|
||||
# Set default API URL
|
||||
attune config set api_url http://localhost:8080
|
||||
|
||||
# Set default profile
|
||||
attune config set profile production
|
||||
|
||||
# View configuration
|
||||
attune config show
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Authentication errors:**
|
||||
```bash
|
||||
# Re-login
|
||||
attune auth login
|
||||
|
||||
# Check token
|
||||
attune auth token
|
||||
|
||||
# Refresh token
|
||||
attune auth refresh
|
||||
```
|
||||
|
||||
**Pack already exists:**
|
||||
```bash
|
||||
# Use --force to replace
|
||||
attune pack install slack@1.0.0 --force
|
||||
```
|
||||
|
||||
**Network timeouts:**
|
||||
```bash
|
||||
# Increase timeout (via environment variable for now)
|
||||
export ATTUNE_ACTION_TIMEOUT=600
|
||||
attune pack install large-pack@1.0.0
|
||||
```
|
||||
|
||||
**Missing dependencies:**
|
||||
```bash
|
||||
# Install dependencies first
|
||||
attune pack install core@1.0.0
|
||||
attune pack install dependent-pack@1.0.0
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Pack Installation Actions Documentation](pack-installation-actions.md)
|
||||
- [Pack Structure](pack-structure.md)
|
||||
- [Pack Registry](pack-registry-spec.md)
|
||||
- [CLI Configuration](../crates/cli/README.md)
|
||||
Reference in New Issue
Block a user