Swamp Model Skill

Work with swamp models through the CLI. All commands support --json for machine-readable output.

CRITICAL: Model Creation Rules

• Never generate model IDs — no uuidgen, crypto.randomUUID(), or manual UUIDs. Swamp assigns IDs automatically via swamp model create.
• Never write a model YAML file from scratch — always use swamp model create <type> <name> --json first, then edit the scaffold at the returned path, preserving the assigned id.
• Never modify the id field in an existing model file.
• Verify CLI syntax: If unsure about exact flags or subcommands, run swamp help model for the complete, up-to-date CLI schema.

Correct flow: swamp model create <type> <name> --json → set global args with --global-arg or edit the YAML → validate → run.

Quick Reference

Repository Structure

Swamp uses a dual-layer architecture:

• Data directory (/.swamp/) - Internal storage organized by entity type
• Logical views (/models/) - Human-friendly symlinked directories

/models/{model-name}/
  input.yaml → ../.swamp/definitions/{type}/{id}.yaml
  resource.yaml → ../.swamp/data/{type}/{id}/{specName}/latest/raw  (type=resource)
  outputs/ → ../.swamp/outputs/{type}/{id}/
  files/ → ../.swamp/data/{type}/{id}/ (filtered by type=file)

Use swamp repo index to rebuild if symlinks become out of sync.

Search for Model Types

Find available model types in the system.

bash
1swamp model type search --json
2swamp model type search "echo" --json

Output shape:

json
1{
2  "query": "",
3  "results": [
4    { "raw": "command/shell", "normalized": "command/shell" }
5  ]
6}

Describe Model Types

Get the full schema and available methods for a type.

bash
1swamp model type describe command/shell --json

Output shape:

json
1{
2  "type": { "raw": "command/shell", "normalized": "command/shell" },
3  "version": "2026.02.09.1",
4  "globalArguments": {/* JSON Schema */},
5  "resourceAttributesSchema": {/* JSON Schema */},
6  "methods": [
7    {
8      "name": "execute",
9      "description": "Execute a shell command and capture output",
10      "arguments": {/* JSON Schema */}
11    }
12  ]
13}

Key fields:

• globalArguments - JSON Schema for input YAML globalArguments section
• methods - Available operations with their per-method arguments schemas

Create Model Inputs

bash
1swamp model create command/shell my-shell --json

Set globalArguments at creation time with --global-arg (repeatable):

bash
1swamp model create aws/ec2/vpc my-vpc \
2  --global-arg region=us-east-1 \
3  --global-arg cidrBlock=10.0.0.0/16 \
4  --json

Dot notation creates nested objects:

bash
1--global-arg config.db.host=localhost --global-arg config.db.port=5432
2# → globalArguments: { config: { db: { host: "localhost", port: "5432" } } }

Output shape:

json
1{
2  "path": "definitions/command/shell/my-shell.yaml",
3  "type": "command/shell",
4  "name": "my-shell"
5}

After creation, edit the YAML file to set per-method arguments in the methods section.

Example input file:

yaml
1id: 550e8400-e29b-41d4-a716-446655440000
2name: my-shell
3version: 1
4tags: {}
5methods:
6  execute:
7    arguments:
8      run: "echo 'Hello, world!'"

Definition-Level Check Selection

Definitions can control which pre-flight checks run via the checks field:

yaml
1id: 550e8400-e29b-41d4-a716-446655440000
2name: my-vpc
3version: 1
4tags: {}
5checks:
6  require:
7    - no-cidr-overlap # Must run, immune to --skip-checks CLI flags
8  skip:
9    - slow-api-check # Always skipped
10globalArguments:
11  cidrBlock: "10.0.0.0/16"
12methods:
13  create:
14    arguments: {}

Precedence rules:

• skip always wins — even over require for the same check name
• require makes checks immune to --skip-checks, --skip-check <name>, and --skip-check-label <label> CLI flags (e.g., --skip-checks skips non-required checks but required checks still run)
• require checks still respect appliesTo method scoping
• model validate honors skip lists and warns on require/skip overlap; validation errors if a check name doesn't exist on the model type

Model Inputs Schema

Models can define an inputs schema for runtime parameterization:

yaml
1id: 550e8400-e29b-41d4-a716-446655440000
2name: my-deploy
3version: 1
4tags: {}
5inputs:
6  properties:
7    environment:
8      type: string
9      enum: ["dev", "staging", "production"]
10      description: Target environment
11    dryRun:
12      type: boolean
13      default: false
14  required: ["environment"]
15globalArguments:
16  target: ${{ inputs.environment }}
17  simulate: ${{ inputs.dryRun }}
18methods:
19  deploy:
20    arguments: {}

Inputs are provided at runtime with --input or --input-file and referenced in globalArguments using ${{ inputs.<name> }} expressions.

Factory pattern: Use inputs to create multiple instances from one model definition — see references/scenarios.md#scenario-5.

Edit a Model

Recommended: Use swamp model get <name> --json to get the file path, then edit directly with the Edit tool, then validate with swamp model validate <name> --json.

Alternative methods:

• Interactive: swamp model edit my-shell (opens in system editor)
• Stdin: cat updated.yaml | swamp model edit my-shell --json

Run swamp repo index if search results seem stale after editing.

Delete a Model

Delete a model and all related artifacts (data, outputs, logs).

bash
1swamp model delete my-shell --json

Output shape:

json
1{
2  "deleted": true,
3  "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
4  "modelName": "my-shell",
5  "artifactsDeleted": {
6    "outputs": 5,
7    "dataItems": 3
8  }
9}

Validate Model Inputs

Validate a model definition against its type schema. Use --label to run only checks with a specific label, and --method to simulate validation for a specific method context.

bash
1swamp model validate my-shell --json
2swamp model validate --json                          # Validate all models
3swamp model validate my-shell --label policy --json  # Only checks with label "policy"
4swamp model validate my-shell --method create --json # Validate for a specific method

Output shape (single):

json
1{
2  "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
3  "modelName": "my-shell",
4  "type": "command/shell",
5  "validations": [
6    { "name": "Definition schema", "passed": true },
7    { "name": "Global arguments", "passed": true },
8    { "name": "Expression paths", "passed": true }
9  ],
10  "warnings": [
11    {
12      "name": "Environment variables detected",
13      "message": "Data stored under this model will vary depending on these environment variables at runtime. Consider using separate models per environment, or vault.get() for sensitive values.",
14      "envVars": [
15        { "path": "globalArguments.baseUrl", "envVar": "JENKINS_BASE_URL" }
16      ]
17    }
18  ],
19  "passed": true
20}

Output shape (all):

json
1{
2  "models": [
3    { "modelId": "...", "modelName": "my-shell", "validations": [...], "warnings": [...], "passed": true }
4  ],
5  "totalPassed": 5,
6  "totalFailed": 1,
7  "totalWarnings": 1,
8  "passed": false
9}

IMPORTANT: Handling Validation Warnings

When warnings is non-empty, STOP and ask the user before proceeding. The most common warning is "Environment variables detected" — this means the model's behavior depends on env vars that may differ between machines or environments.

• If warnings contains env var usage, tell the user which fields use which env vars and ask if this is intentional.
• Suggest alternatives: separate models per environment (e.g., prod-jenkins and dev-jenkins with hardcoded values), or vault.get() for sensitive values.
• Never silently run a method on a model with env var warnings without user confirmation — the data artifacts will be stored under the model name and may contain results from an unintended environment.

Expression Language

Model inputs support CEL expressions using ${{ <expression> }} syntax. Reference types, data versioning functions, and examples are in references/expressions.md.

Evaluate Model Inputs

Evaluate expressions and write results to inputs-evaluated/.

bash
1swamp model evaluate my-subnet --json
2swamp model evaluate --all --json

Output shape:

json
1{
2  "evaluatedInputs": [
3    {
4      "name": "my-subnet",
5      "type": "aws/subnet",
6      "path": "inputs-evaluated/aws/subnet/my-subnet.yaml"
7    }
8  ]
9}

Run Methods

Execute a method on a model input.

bash
1swamp model method run my-shell execute --json
2swamp model method run my-deploy create --input environment=prod --json
3swamp model method run my-deploy create --input environment=prod --input replicas=3 --json
4swamp model method run my-deploy create --input config.timeout=30 --json  # dot notation for nesting
5swamp model method run my-deploy create --input '{"environment": "prod"}' --json  # JSON also supported
6swamp model method run my-deploy create --input-file inputs.yaml --json
7swamp model method run my-deploy create --last-evaluated --json
8swamp model method run my-deploy create --skip-checks --json
9swamp model method run my-deploy create --skip-check valid-region --json
10swamp model method run my-deploy create --skip-check-label live --json

Pre-flight checks run automatically before mutating methods (create, update, delete, action). Read-only methods (sync, get, etc.) do not trigger checks.

Environment variable warnings are emitted before execution if the model definition uses ${{ env.* }} expressions. When you see these warnings in the output, pause and confirm with the user that the current environment variables are correct for the intended target. See Handling Validation Warnings above.

Options:

Output shape:

json
1{
2  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
3  "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
4  "modelName": "my-shell",
5  "method": "execute",
6  "status": "succeeded",
7  "duration": 150,
8  "artifacts": {
9    "resource": ".swamp/data/command/shell/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/result/1/raw"
10  }
11}

Model Outputs

Search Outputs

Find method execution outputs.

bash
1swamp model output search --json
2swamp model output search "my-shell" --json

Output shape:

json
1{
2  "query": "",
3  "results": [
4    {
5      "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
6      "modelName": "my-shell",
7      "method": "execute",
8      "status": "succeeded",
9      "createdAt": "2025-01-15T10:30:00Z"
10    }
11  ]
12}

Get Output Details

Get full details of a specific output or latest output for a model.

bash
1swamp model output get d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json
2swamp model output get my-shell --json  # Latest output for model

Output shape:

json
1{
2  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
3  "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
4  "modelName": "my-shell",
5  "type": "command/shell",
6  "method": "execute",
7  "status": "succeeded",
8  "startedAt": "2025-01-15T10:30:00Z",
9  "completedAt": "2025-01-15T10:30:00.150Z",
10  "artifacts": [
11    { "type": "resource", "path": "..." }
12  ]
13}

View Output Logs

Get log content from a method execution.

bash
1swamp model output logs d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json

Output shape:

json
1{
2  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
3  "logs": "Executing shell command...\nHello, world!\nCommand completed successfully."
4}

View Output Data

Get data artifact content from a method execution.

bash
1swamp model output data d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json

Output shape:

json
1{
2  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
3  "data": {
4    "exitCode": 0,
5    "command": "echo 'Hello, world!'",
6    "executedAt": "2025-01-15T10:30:00Z"
7  }
8}

Workflow Example

1. Search for the right type: swamp model type search "shell" --json
2. Search community if no local type: swamp extension search <query> --json — if a matching extension exists, install it with swamp extension pull <package> instead of building from scratch
3. Describe to understand the schema: swamp model type describe command/shell --json
4. Create an input file: swamp model create command/shell my-shell --json
5. Edit the YAML file to set methods.execute.arguments.run
6. Validate the model: swamp model validate my-shell --json
7. Check warnings — if the validation output has non-empty warnings, stop and ask the user before proceeding (see Handling Validation Warnings)
8. Run the method: swamp model method run my-shell execute --json
9. View the output: swamp model output get my-shell --json

Data Ownership

Data is owned by the creating model — see references/data-ownership.md for rules and validation.

When to Use Other Skills

References

• Examples: See references/examples.md for complete model workflows and CEL expression reference
• Troubleshooting: See references/troubleshooting.md for common errors and fixes
• Scenarios: See references/scenarios.md for end-to-end scenarios (shell commands, chained lookups, runtime inputs)
• Data chaining: See references/data-chaining.md for command/shell model examples and chaining patterns
• Execution drivers: See references/execution-drivers.md