scenario
The scenario group inspects and controls lab scenarios from the command line. It is intended for AI agents: errors print a concrete next action, output is capped with --limit to protect the agent's context, and --format json is available for reliable parsing. Most commands are read-only (search, info, running, protocol, resources, error); the two state-changing commands (start, stop) require an explicit --yes confirmation.
A typical flow is to search for a scenario, look at its info, inspect its error if it failed, and list the resources it produced.
scenario search
Searches scenarios using the advanced, operator-based search. Pass a JSON list of filter criteria to --filter, where each criterion is {"key": <field>, "operator": <OP>, "value": <val>}. Results are paginated and can be returned as a table (default) or JSON.
gws scenario search [OPTIONS]
# Find all errored scenarios
gws scenario search --filter '[{"key":"status","operator":"EQ","value":"ERROR"}]'
# Errored scenarios whose title contains "import", newest first, as JSON
gws scenario search \
--filter '[{"key":"status","operator":"EQ","value":"ERROR"},{"key":"title","operator":"CONTAINS","value":"import"}]' \
--sort '[{"key":"created_at","direction":"DESC"}]' \
--format json
scenario info
Shows a single scenario's metadata as JSON. Find scenario ids with gws scenario search.
gws scenario info [OPTIONS]
gws scenario info abc123
scenario running
Lists the scenarios that are currently running, together with each running task's progress and last message. Output can be a table (default) or JSON.
gws scenario running [OPTIONS]
gws scenario running
scenario error
Shows the failure info of a scenario as JSON, when it errored. If the scenario has no error info, the command prints its title and current status instead.
gws scenario error [OPTIONS]
gws scenario error abc123
scenario protocol
Prints a scenario's protocol as JSON — the full process graph, following the same path as the /protocol/{id} GET endpoint. Use this to inspect the tasks, connectors, and structure of a workflow.
gws scenario protocol [OPTIONS]
gws scenario protocol abc123
scenario resources
Lists the resources a scenario produced and consumed. Each row shows the resource id, name, typing name, and whether it is flagged. Inspect an individual resource further with the gws resource group. Output can be a table (default) or JSON.
gws scenario resources [OPTIONS]
gws scenario resources abc123 --format json
scenario start
Starts a scenario by queuing it for execution. This changes scenario state, so it is not run by default: you must pass --yes to confirm. On success it prints the scenario title and its new status.
gws scenario start --yes [OPTIONS]
gws scenario start abc123 --yes
scenario stop
Stops a running scenario. This changes scenario state, so it is not run by default: you must pass --yes to confirm. On success it prints the scenario title and its new status.
gws scenario stop --yes [OPTIONS]
gws scenario stop abc123 --yes
