framework-ignition-docker/.claude/commands/ignition-configure.md

# ignition-configure

Use this skill whenever the user asks you to configure, inspect, or manage the Ignition gateway
via the HTTP API — adding connections, importing tags, checking status, managing modules, etc.

## Setup: Resolve token and host

1. Read `docker/.env` for `GATEWAY_HOSTNAME` (default: `localhost:8088`)
2. Read `~/.config/ignition-dev/secrets.env` for `IGNITION_API_TOKEN` (format: `name:token`)
   - Fall back to asking the user if not found
3. Set shell variables for all subsequent calls:

```bash
TOKEN=$(grep IGNITION_API_TOKEN ~/.config/ignition-dev/secrets.env | cut -d= -f2)
GW="http://$(grep GATEWAY_HOSTNAME docker/.env | cut -d= -f2- || echo 'localhost:8088')"
HEADER="X-Ignition-API-Token: $TOKEN"
```

## Step 1: Confirm gateway is reachable

Always check before making changes:

```bash
curl -s -H "$HEADER" $GW/data/api/v1/overview | python3 -m json.tool
```

If this fails, check `docker compose ps` and gateway logs before proceeding.

## Step 2: Inspect current state

Before creating or modifying anything, read what's already there:

```bash
# Gateway connections overview
curl -s -H "$HEADER" $GW/data/api/v1/overview/connections | python3 -m json.tool

# Any critical problems
curl -s -H "$HEADER" $GW/data/api/v1/overview/problems | python3 -m json.tool
```

---

## Common Configuration Tasks

### Add a database connection

```bash
# First — describe the schema to see available props
curl -s -H "$HEADER" $GW/data/api/v1/resources/type/ignition/database-connection | python3 -m json.tool

# Create
curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
  $GW/data/api/v1/resources/ignition/database-connection \
  -d '{
    "name": "ignition_db",
    "enabled": true,
    "props": {
      "ConnectURL": "jdbc:postgresql://postgres:5432/ignition",
      "Username": "ignition",
      "Password": "'"$POSTGRES_PASSWORD"'"
    }
  }'

# Verify
curl -s -H "$HEADER" $GW/data/api/v1/resources/find/ignition/database-connection/ignition_db | python3 -m json.tool
```

### Add an OPC connection (Modbus or AB PLC)

```bash
# Describe schema first
curl -s -H "$HEADER" $GW/data/api/v1/resources/type/ignition/opc-connection | python3 -m json.tool

# Create
curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
  $GW/data/api/v1/resources/ignition/opc-connection \
  -d '{
    "name": "modbus-sim-pumps",
    "enabled": true,
    "props": {
      "EndpointUrl": "opc.tcp://modbus-sim-pumps:4840",
      "SecurityPolicy": "None",
      "MessageSecurity": "None"
    }
  }'
```

### Add an OPC-UA device

```bash
# List available device types
curl -s -H "$HEADER" $GW/data/api/v1/resources/type/com.inductiveautomation.opcua/device | python3 -m json.tool

# Create
curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
  $GW/data/api/v1/resources/com.inductiveautomation.opcua/device \
  -d '{ "name": "MyDevice", "enabled": true, "props": { ... } }'
```

### Modify an existing resource

Always GET first to obtain the current `signature`:

```bash
# Step 1: Get current config and signature
RESOURCE=$(curl -s -H "$HEADER" $GW/data/api/v1/resources/find/ignition/database-connection/ignition_db)
SIG=$(echo $RESOURCE | python3 -c "import json,sys; print(json.load(sys.stdin)['signature'])")

# Step 2: Modify (include signature in body)
curl -s -X PUT -H "$HEADER" -H "Content-Type: application/json" \
  $GW/data/api/v1/resources/ignition/database-connection \
  -d "{\"name\": \"ignition_db\", \"signature\": \"$SIG\", \"props\": { ... }}"
```

### Import tags

```bash
# Export first (to see current state or create a template)
curl -s -H "$HEADER" \
  "$GW/data/api/v1/tags/export?provider=default&path=Devices&recursive=true" \
  -o tags-export.json

# Import (collisionPolicy: Abort | Overwrite | Ignore | MergeOverwrite | MergeIgnore)
curl -s -X POST -H "$HEADER" -H "Content-Type: application/json" \
  "$GW/data/api/v1/tags/import?provider=default&path=Devices&collisionPolicy=MergeOverwrite" \
  -d @tags-export.json
```

### Download a backup

```bash
curl -s -H "$HEADER" \
  "$GW/data/api/v1/backup" \
  -o "gateway-$(date +%Y%m%d-%H%M%S).gwbk"
```

---

## After Making Changes — Scan to Sync

After editing files in `ignition/project/`:
```bash
curl -s -X POST -H "$HEADER" $GW/data/api/v1/scan/projects
```

After editing files in `docker/gw-config/`:
```bash
curl -s -X POST -H "$HEADER" $GW/data/api/v1/scan/config
```

Check scan status:
```bash
curl -s -H "$HEADER" $GW/data/api/v1/scan/projects | python3 -m json.tool
curl -s -H "$HEADER" $GW/data/api/v1/scan/config | python3 -m json.tool
```

---

## Gateway Restart ⚠️

**Never restart without explicit user confirmation.** Check for pending tasks first:

```bash
# Check what requires a restart
curl -s -H "$HEADER" $GW/data/api/v1/restart-tasks/pending | python3 -m json.tool

# Restart (confirm=true required — disruptive to all active sessions)
curl -s -X POST -H "$HEADER" "$GW/data/api/v1/restart-tasks/restart?confirm=true"
```

---

## Logs and Diagnostics

```bash
# Recent warnings and errors
curl -s -H "$HEADER" "$GW/data/api/v1/logs?minLevel=WARN&limit=50" | python3 -m json.tool

# Logs for a specific logger
curl -s -H "$HEADER" "$GW/data/api/v1/logs?logger=IgnitionGateway&limit=25" | python3 -m json.tool

# Audit trail
curl -s -H "$HEADER" "$GW/data/api/v1/audit/log/Audit?limit=25" | python3 -m json.tool
```

---

## Reference

Full API reference: [ignition/ignition-api.md](../../ignition/ignition-api.md)
Live spec: `http://localhost:8088/openapi`