attune/docs/QUICKREF-dev-packs.md

Quick Reference: Development Packs

Setup (One Time)

# Directory is already created, just start Docker
docker compose up -d

Create a Pack

./scripts/dev-pack.sh create my-pack

Creates:

• packs.dev/my-pack/pack.yaml
• packs.dev/my-pack/actions/example.sh
• Example action YAML
• README

List Packs

./scripts/dev-pack.sh list

Validate Pack

./scripts/dev-pack.sh validate my-pack

Checks:

• ✓ pack.yaml exists
• ✓ Action scripts exist and are executable
• ✓ Entry points match

Register Pack in Attune

# Get token first
export ATTUNE_TOKEN=$(attune auth login test@attune.local --password TestPass123!)

# Register pack
curl -X POST http://localhost:8080/api/v1/packs \
  -H "Authorization: Bearer $ATTUNE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "my-pack",
    "label": "My Pack",
    "version": "1.0.0",
    "enabled": true
  }'

Execute Action

curl -X POST http://localhost:8080/api/v1/executions \
  -H "Authorization: Bearer $ATTUNE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "my-pack.example",
    "parameters": {
      "message": "Hello!"
    }
  }'

Directory Layout

packs.dev/
├── examples/              # Example packs (in git)
│   ├── basic-pack/       # Shell action example
│   └── python-pack/      # Python action example
└── my-pack/              # Your packs (not in git)
    ├── pack.yaml
    ├── actions/
    ├── triggers/
    ├── sensors/
    └── workflows/

File Locations in Docker

• Core pack: /opt/attune/packs (read-only)
• Dev packs: /opt/attune/packs.dev (read-write)

Development Workflow

1. Create pack: ./scripts/dev-pack.sh create my-pack
2. Edit files: vim packs.dev/my-pack/actions/my_action.sh
3. Validate: ./scripts/dev-pack.sh validate my-pack
4. Register: See "Register Pack" above
5. Test: Execute action via API
6. Iterate: Changes are immediately visible!

Action Script Template

#!/bin/bash
set -e

# Get parameters from environment
PARAM="${ATTUNE_ACTION_param:-default}"

# Validate
if [ -z "$PARAM" ]; then
    echo '{"error": "param required"}' >&2
    exit 1
fi

# Do work
result=$(echo "Processed: $PARAM")

# Return JSON
echo "{\"result\": \"$result\"}"

Common Commands

# List all packs
./scripts/dev-pack.sh list

# Validate pack structure
./scripts/dev-pack.sh validate my-pack

# View pack in container
docker exec attune-api ls -la /opt/attune/packs.dev/

# Check worker logs
docker logs -f attune-worker-shell

# Sync workflows after changes
curl -X POST http://localhost:8080/api/v1/packs/my-pack/workflows/sync \
  -H "Authorization: Bearer $ATTUNE_TOKEN"

# Clean up dev packs
./scripts/dev-pack.sh clean

Troubleshooting

"Pack not found"

# Check if registered
curl http://localhost:8080/api/v1/packs/my-pack \
  -H "Authorization: Bearer $ATTUNE_TOKEN"

# Check if files exist in container
docker exec attune-api ls /opt/attune/packs.dev/my-pack/

"Entry point not found"

# Make script executable
chmod +x packs.dev/my-pack/actions/*.sh

# Verify in container
docker exec attune-worker-shell ls -la /opt/attune/packs.dev/my-pack/actions/

Changes not reflected

# For action scripts: should be immediate
# For action YAML: re-register pack
# For workflows: run sync endpoint

See Also

• Full Documentation
• Pack Structure
• Examples