Command Reference

Command reference

Run commands from the repository containing .SYSTEMX, or invoke its launcher using an absolute path. Configured project commands always execute from that repository's root.

bash .SYSTEMX/SYSTEMX.sh --help

The compatibility launcher .SYSTEMX/WSG-MENU.sh accepts the same arguments. On native Windows, use py -3 .SYSTEMX/scripts/systemx.py with the same command and flags.

Inspection and setup

Command	Behavior
No arguments or menu	Open the interactive menu; EOF exits.
help or --help	Print command usage.
validate	Check template files, JSON/config structure, local Markdown file links, coordination records, and generated work views.
doctor	Report paths, Python version, available Git state, configuration, and executable availability.
init	Create .SYSTEMX/project.json; refuse to overwrite it.
status	Print recorded task counts, open work, and registered role IDs.
context --agent agent.0	Load shared context, master plan, project memory, selected agent notes, and relevant open-task summaries.
refresh-work	Regenerate all six work views from valid canonical records.

doctor does not contact services or prove authentication. validate does not check external URLs, heading anchors, application behavior, or the truth of recorded evidence. context defaults to agent.0 and labels truncated output.

Project commands

Command	Execution order
check	Template validation, then configured checks in order
dev	Template validation, then the configured development command
build	Template validation, configured checks, then build
deploy	Template validation, configured checks, build, then deployment

Each supports --dry-run, which prints the plan without running project commands. Required empty configuration fails. Before executing a plan, the runner checks executable availability for every step; a failed executed command stops the sequence. Configure scripts carefully: the runner does not choose an environment, authenticate, commit, push, or perform a live smoke check.

Register a worker

bash .SYSTEMX/SYSTEMX.sh agent-add agent.1 --role test

The worker ID must use agent. followed by a positive integer. agent.0 is the existing coordinator. Registration creates a memory file and registry entry, without starting an agent process or overwriting an existing worker.

Create a task

bash .SYSTEMX/SYSTEMX.sh task-add --title 'Task title' --acceptance 'Acceptance criterion'

Flag	Required?	Meaning
--title	Yes	Nonempty task title
--acceptance	Yes; repeatable	Acceptance criteria
--owner	No	Registered owner; defaults to agent.0
--scope	No; repeatable	Intended files or systems in scope
--depends-on	No; repeatable	Existing prerequisite task IDs
--milestone	No	ID declared in the master-plan table
--next	No	Concrete next action

New tasks start at todo and receive the next TASK-001-style ID.

Inspect or update a task

bash .SYSTEMX/SYSTEMX.sh task-show TASK-001
bash .SYSTEMX/SYSTEMX.sh task-set TASK-001 --status in_progress --next 'Concrete next action'

task-set flag	Meaning
--status	One of todo, in_progress, blocked, needs_review, done, cancelled
--owner	Reassign to a registered role
--next	Set the next action; required to be nonempty for in_progress
--blocker	Explain what prevents progress; required for blocked
--evidence	Append an evidence reference; repeat for multiple entries
--reviewer	Record agent.0 or user when accepting done
--note	Add a history note; required when cancelling work

At least one change or note is required. Transition and dependency rules apply; see Task workflow. Completed or cancelled tasks reopen to todo before further editing.

Exit behavior

• 0: the requested operation succeeded within its documented scope.
• 2: usage, configuration, record-validation, or handled file errors.
• A failed project command's positive exit status is returned by the runner.
• An interrupted CLI returns 130.

The interactive menu reports an action's failure and returns to the menu. For automation that needs a reliable action exit status, invoke the command directly.