Writing Your First Script

This guide walks you through creating and running a mentu script from scratch.

Prerequisites

• mentu CLI installed (mentu --version should print output)
• Node.js 20+ installed
• Authenticated (mentu auth login you@example.com)

1. Create the scripts directory

mkdir -p ~/.mentu/scripts

This is the global scripts directory. mentu also checks {workspace}/.mentu/scripts/ for project-scoped scripts.

2. Write the script

Create ~/.mentu/scripts/hello.ts:

// Query the CIR substrate for recent signals
const stats = mentu.cir.stats();
const recent = mentu.cir.query({ since: '24h', limit: 5 });
 
// Log what we found
console.log(`CIR has ${stats.signals} signals total`);
console.log(`${recent.length} signals in the last 24 hours`);
 
// List each recent signal
for (const signal of recent) {
  console.log(`  [${signal.type}] ${signal.body}`);
}
 
// The return value is printed as JSON after console output
return { total: stats.signals, recent: recent.length };

Every script has access to the mentu global object. No imports needed — the SDK is injected into the V8 sandbox automatically.

3. Run the script

mentu script run hello

Output:

CIR has 245123 signals total
3 signals in the last 24 hours
  [observation] API latency exceeded 500ms threshold
  [classification] Infrastructure health: nominal
  [observation] Deployment completed successfully
{
  "total": 245123,
  "recent": 3
}

The script's console.log output appears first, followed by the return value as formatted JSON.

4. Understanding output

Script output has two parts:

1. Console output — every console.log(), console.warn(), console.error() call during execution
2. Return value — the final expression's value, printed as JSON (or as-is for strings)

If your script does not return anything, only console output appears.

5. Adding variables

Variables let you parameterize scripts without editing them. Pass variables with --var:

mentu script run hello --var SINCE=7d --var LIMIT=20

Access them in the script via mentu.vars:

const since = mentu.vars.SINCE ?? '24h';
const limit = parseInt(mentu.vars.LIMIT ?? '5', 10);
 
const recent = mentu.cir.query({ since, limit });
console.log(`${recent.length} signals in the last ${since}`);
 
return { count: recent.length };

mentu.vars is a frozen read-only object. If a variable is not passed, accessing it returns undefined.

6. Error handling

When a script fails, mentu reports the error and exits with code 1:

Sandbox error: Cannot read properties of undefined (reading 'foo')

Common failure modes:

You can set a custom timeout:

mentu script run hello --timeout 60

7. Workspace-scoped scripts

Scripts in {workspace}/.mentu/scripts/ take priority over global scripts. This lets you keep project-specific scripts alongside your code:

mkdir -p .mentu/scripts
cat > .mentu/scripts/project-check.ts << 'EOF'
console.log(`Workspace: ${mentu.workspace.path}`);
const stats = mentu.cir.stats();
console.log(`CIR: ${stats.signals} signals`);
return stats;
EOF
 
mentu script run project-check

Next steps

• SDK Reference — every method signature and parameter
• Examples — six complete, runnable scripts
• Dynamic Variables — patterns for parameterizing scripts
• Scheduling Scripts — run scripts on a cron schedule with temporals