Running Scripts

Run predefined REPL command sequences from coco.nut:

coco lab run <script-name>

coco lab init

Sets up a session for the module in coco.nut and then opens the REPL. The project must already be initialized (use coco nut init to create a new coco.nut).

Unless --new-session or --no-persist is given, init first restores the saved snapshot. It then runs three commands:

1. register default_user
2. set default.sender default_user
3. compile <Module>, using the [module] name from coco.nut

It saves a snapshot and opens the REPL. Each step is logged:

INFO - init: 'register default_user' succeeded
INFO - init: 'set default.sender default_user' succeeded
INFO - init: 'compile ContextFlipper' succeeded

Running init again is safe. A step that's already done is logged as skipped, and a real failure is logged at ERROR level:

INFO - init: 'register default_user' skipped, already set up (user already exists: default_user)
INFO - init: 'compile ContextFlipper' skipped, already set up (var name ContextFlipper already used in Logics. Please use another name)
ERROR - init: '<command>' failed: <error>

Changed in v0.9.2

Before v0.9.2 every outcome was logged at debug level, so coco lab init --new-session looked as if it did nothing.

Defining Scripts

In coco.nut:

[lab.scripts]
test-toggle = ["engines", "users", "logics"]
my-test = ["compile MyLogic", "deploy MyLogic.Init()", "invoke MyLogic.Run()"]

Scripts created by default with coco nut init.

Persistence

State persists across separate coco lab run invocations that share the same storage location: each run restores the latest snapshot before executing and saves a new one afterward. Use --new-session to ignore the prior snapshot, or --no-persist for a hermetic run (point --storage-path at a fresh directory to fully isolate it).

Bash Verification Scripts

The [scripts] section defines bash commands that can run lab scripts and verify output:

[scripts]
test = '''
PASS=0
FAIL=0
TEST_RESULTS=$(coco lab run my-test --new-session --no-color 2>&1)

echo "$TEST_RESULTS" | grep -qE 'balance:100( |$)' \
    && { echo 'PASS: test name'; PASS=$((PASS+1)); } \
    || { echo 'FAIL: test name'; FAIL=$((FAIL+1)); }

echo "Results: $PASS passed, $FAIL failed out of $((PASS+FAIL)) tests"
if [ "$FAIL" -gt 0 ]; then exit 1; fi
'''

Run with: coco nut run test

Two details keep such a script reliable:

• Pass --new-session (or --no-persist). Without it, coco lab run can restore the previous run's snapshot. Setup steps then fail on the second run (a repeated grant reports access policy already exists), and state accumulates: a balance credited by the script keeps growing from run to run.
• Anchor the value. grep -q 'balance:100' also matches balance:1000. Outputs are printed as space-separated name:value pairs, so end the pattern with ( |$) as above, or with $ when the value is the last one on the line.

Use --no-color when grepping

Cocolab colors values in its output, so a line such as Execution Outputs ||| flag:true arrives with ANSI escape codes around flag:true. A simple substring match still works, but a pattern anchored to the start or end of a value, or one that spans two values, can silently fail. --no-color (added in v0.9.1) prints the output as plain text. Since v0.9.2 it also covers the error: Unrecognized token … line that a mistyped command produces.

CLI Flags

Flag	Description
-c, --config	Config name from [lab.config.name]
-e, --env	Environment (default: main)
-o, --os	Override target OS
-s, --suppress	Suppress output
-x, --no-exit	Don't exit the REPL after the script runs
--debug	Print each lab command before execution
--no-color	Strip ANSI color codes from the output, including command parse errors
--no-persist	Disable session persistence (state is discarded on exit)
--new-session	Start a fresh session (ignore persisted state) but keep saving
--storage	Storage backend type (default: file; overrides coco.nut)
--storage-path	Backend-specific location, e.g. a folder path (overrides coco.nut)

coco lab run test-toggle -s