CLI Reference

Commands & Flags

Complete reference for the pseudo command-line interface.

Commands

Command	Description
`pseudo run <file>`	Run a `.pseudo` or `.psu` file
`pseudo validate <file>`	Validate a source or `.pmap` file without running
`pseudo explain <line>`	Show what a line of pseudo maps to
`pseudo init`	Create a custom.pmap and local pseudo.config
`pseudo version`	Print the installed version

pseudo run - Flags

Flag	Type	Default	Description
--lang <file>	path	`-`	Use a specific .pmap file instead of auto-detected
-i <input>	string/file	`-`	Inline input or input file (repeatable). Use \n for multiple values
--analyze	flag	`off`	Show Big-O complexity analysis after run
--explain	flag	`off`	With --analyze: show reasoning for complexity
--summary	flag	`off`	With --analyze: one-line output
--timeout <N>	float	`5.0`	Execution timeout in seconds (0 = unlimited)
--max-iter <N>	int	`10,000,000`	Maximum loop iterations before halting
--dry-run	flag	`off`	Show mapping resolution - do not execute
--step	flag	`off`	Step through line-by-line (educational debugger)
--no-auto-print	flag	`off`	Disable automatic printing of standalone expressions

Examples

Basic run

bash

pseudo run algorithm.pseudo

Pass input values

bash

pseudo run greet.pseudo -i "Alice"
pseudo run greet.pseudo -i "Alice\n25"   # multiple inputs
pseudo run greet.pseudo -i inputs.txt    # from file

Use a custom pmap

bash

pseudo run algo.pseudo --lang custom.pmap
pseudo run algo.pseudo --lang ~/my_lang.pmap

Dry run - inspect mapping

bash

pseudo run sort.pseudo --dry-run

Output

Line 1: "func bubbleSort(arr)" → FUNC_DEF: name=bubbleSort, args=[arr] Line 2: " for i from 0 to len(arr)" → FOR_LOOP: var=i, start=0, end=len(arr) No errors found. Safe to run.

Complexity analysis

bash

pseudo run sort.pseudo --analyze

Output

Time: O(n²) Space: O(1)

Explain a mapping

bash

pseudo explain "for i from 0 to n"
pseudo explain --list FOR_LOOP

Output

Using: default.pmap Matched pattern : 'for {var:name} from {start:expr} to {end:expr}' Canonical form : FOR_LOOP Captures : {var} = 'i' {start} = '0' {end} = 'n'

Validate a pmap file

bash

pseudo validate custom.pmap

Output

Validating custom.pmap... ✓ 12 patterns loaded. No errors found.

pmap Resolution Order

When running a file, Pseudo picks the .pmap to use in this order:

--lang flag - explicitly specified pmap wins
pseudo.config - local project config in current directory
~/.pseudo/custom/custom.pmap - your global custom pmap
~/.pseudo/core/default.pmap - the bundled default (English)