CREATE AND RUN A BEHAVIOR

Prerequisites: Swamp installed, a repository initialized with swamp repo init.

Repositories and scripts that use the older command spelling keep working; see Compatibility with model commands.

Search for available behavior types

swamp behavior type search

{
  "query": "",
  "results": [
    {
      "raw": "command/shell",
      "normalized": "command/shell"
    }
  ]
}

Installed extensions add their types to this list. To install more, see extensions.

Inspect a type before using it

swamp behavior type describe command/shell

Type: command/shell
Version: 2026.02.09.1

Data Outputs:
  result [resource] - Shell command execution result (exit code, timing, command) (infinite)
  log [file] - Shell command output (stdout and stderr) (text/plain, infinite)

Methods:
  execute - Execute the shell command and capture stdout, stderr, and exit code
    Inputs:
      run (string) *required
      workingDir (string)
      timeout (integer)
      env (object)
      ignoreExitCode (boolean)

Create a behavior definition

swamp behavior create command/shell my-greeter

Created: my-greeter (command/shell)
Path: models/command/shell/my-greeter.yaml
Version: 2026.02.09.1
...

This writes a YAML definition under models/. The file contains the type, name, and empty globalArguments and methods blocks you can edit. For the full definition schema, see the behavior definitions reference.

Validate the definition

swamp behavior validate my-greeter

Validating: my-greeter (command/shell)
  ✓ Definition schema
  ✓ Type version
  ✓ Global arguments
  ✓ Method arguments
  ✓ Expression paths
  ✓ Check selection
Summary: 6/6 validations passed
Result: PASSED

Run a method

swamp behavior run my-greeter execute --input 'run=echo Hello from the swamp!'

   Resolved   my-greeter (command/shell)
  Executing   execute · 04:02:07 UTC
              Hello from the swamp!

  Completed   execute on my-greeter succeeded in 19ms · 04:02:07 UTC
...

Each method run produces data artifacts according to the type's data output specs.

Inspect the output

To see what data a behavior has produced:

swamp data list my-greeter

Data for my-greeter (command/shell)

file (1 item):
  log  v1  text/plain  30B  2026-10-14

resource (1 item):
  result  v1  application/json  154B  2026-10-14

report (2 items):
  report-swamp-method-summary  v1  text/markdown  543B  2026-10-14
  report-swamp-method-summary-json  v1  application/json  2.7KB  2026-10-14

To retrieve a specific artifact:

swamp data get my-greeter result --json

{
  "id": "...",
  "name": "result",
  "modelId": "...",
  "modelName": "my-greeter",
  "modelType": "command/shell",
  "version": 1,
  "contentType": "application/json",
  "lifetime": "infinite",
  "garbageCollection": 10,
  "streaming": false,
  "tags": {
    "type": "resource",
    "specName": "result",
    "modelName": "my-greeter"
  },
  "ownerDefinition": {
    "ownerType": "model-method",
    "ownerRef": "..."
  },
  "createdAt": "...",
  "size": 121,
  "checksum": "...",
  "contentPath": "...",
  "content": {
    "exitCode": 0,
    "executedAt": "...",
    "command": "echo Hello from the swamp!",
    "durationMs": 4,
    "stdout": "Hello from the swamp!",
    "stderr": ""
  }
}

The execution result is in the content sub-object. The surrounding fields are data-layer metadata (identity, versioning, ownership, tags).

For file outputs like logs:

swamp data get my-greeter log

Data: log (v1)
Model: my-greeter (command/shell)
Content: text/plain, 21B
Lifetime: infinite | GC: 10
Tags: type=file, specName=log, modelName=my-greeter
Owner: model-method (...)
Created: ...
Path: ...

[stdout]
Hello from the swamp!

View method run history

swamp behavior history my-greeter

{
  "id": "...",
  "definitionId": "...",
  "modelName": "my-greeter",
  "type": "command/shell",
  "methodName": "execute",
  "status": "succeeded",
  "startedAt": "2026-10-14T04:02:07.832Z",
  "completedAt": "2026-10-14T04:02:07.851Z",
  "durationMs": 19,
  ...
}

Auto-create with direct type execution

If you want to skip the explicit behavior create step, pass the type directly:

swamp behavior run @command/shell execute my-quick-behavior --input 'run=echo Quick start'

This auto-creates a definition under .swamp/auto-definitions/ and runs the method in a single command. Auto-definitions are not committed to version control.