Command Reference

Command reference

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

bash .SYSTEMX/SYSTEMX.sh --help

The compatibility launcher .SYSTEMX/WSG-MENU.sh accepts the same arguments. On native Windows, use .SYSTEMX\SYSTEMX.ps1 with the same command and flags. For a managed installation, the package command systemx run --target ... -- <command> selects the intended release even when an older root launcher is retained.

Installation and version management

Read release policy before upgrading an older manager to alpha. The tool version and each project's selected defaults version are independent.

These commands belong to the systemx package CLI, also available through python3 -I -B .SYSTEMX/manager.py. All targets are explicit local project roots. The direct manager, runner, and release scripts enter Python isolated mode before imports. When calling them directly, include -I as shown in the examples; the script entry points also enforce that boundary. The installed systemx console command resolves its package first, then restarts isolated before manager import; use a reviewed virtual environment's Python with -I -B -m systemx for isolation from the initial import.

Command	Behavior
--version	Report external tool version, channel, and Python package spelling; no target required
first-run --target PATH	Preview installation/adoption and empty config initialization
first-run --target PATH --apply	Apply first-run setup without running project commands; preserve existing files/settings
audit --target PATH	Offline inspection of the selected folder, case variants, and operation receipts
uninstall --target PATH --backup NEW_PATH	Preview archiving the whole folder, including user records, outside the project
uninstall --target PATH --backup NEW_PATH --apply	Archive, verify, remove the local alias if present, and write an external log
restore --target PATH --backup PATH	Verify a removal backup and preview restoration
restore --target PATH --backup PATH --apply	Restore a verified backup only into an empty destination
setup --profile project	Print a profile's setup URL and persistence model; also directory, drive, or chat
install --target PATH --profile project	Install bundled defaults, append missing files, and pin the version
install --target PATH --version 1.8.9-alpha.1	Install an exact published GitHub release
install --target PATH --source PATH	Install from a reviewed local distribution without downloading
update --target PATH --version 1.8.9-alpha.1	Select an exact release after unlocking; preserve existing project files
install, update, or first-run with --version VERSION --archive-sha256 DIGEST	Pin the exact remote codeload ZIP digest before parsing; obtain it independently
bootstrap-refresh --target PATH --source /reviewed/new/.SYSTEMX	Preview additions, replacements, and conflicts for eight stock root bootstrap and launcher files
bootstrap-refresh --target PATH --source /reviewed/new/.SYSTEMX --apply	Add historically absent stock files and back up/replace recognized stock files; refuse customized or unrecognized files
install or update with --dry-run	Print additions, preserved paths, and conflicts without writing the target
install --target PATH --lowercase-alias	Opt in to a local relative lowercase link; case-insensitive paths need no link
alias --target PATH	Inspect exact stored casing and alias without writing or contacting the network
alias --target PATH --create	Create the local link if needed; --dry-run previews without changing files
policy --target PATH --pin none	Explicitly unlock the selected version
policy --target PATH --pin current	Lock the current selection and reset startup checks to manual
policy --target PATH --auto on-start	With a refreshed 1.8.9 check-only root manager, report available releases at startup, even while pinned; never select one automatically
policy --target PATH --auto manual	Disable startup checks without changing the version selection or pin
status --target PATH	Verify and show defaults version, derived channel, pin, profile, selected archive digest receipt, and retained versions; no network
run --target PATH --offline -- status	Run project task status using installed defaults without a network check
export-chat --target PATH --output NEW_FILE	Write a new local chat packet; no upload or overwrite

Manager status describes the installation. Project run ... -- status describes the task ledger. New installs are pinned and manual. Omitting the version on an unpinned update uses the current selection's channel: final-version projects discover final releases; alpha projects can discover alpha and final releases according to the release policy. Read Installation and updates for retention, startup timing, major-version boundaries, and recovery. A dry run can download and verify a requested release, but it makes no target changes. The 1.8.9 on-start policy reads release metadata and prints a notice; it does not download or select the discovered archive. New selections require a separate explicit update, ideally with --version and an independently obtained --archive-sha256. The older preserved root manager can retain its prior startup-selection behavior; refresh it before enabling check-only notices. --archive-sha256 requires an exact remote --version and cannot be used with --source or unversioned discovery. See the independent archive pin for the digest's exact byte stream and trust boundary.

Run bootstrap-refresh from the reviewed new tool, such as a separate checkout or newly installed package, before update when it reports that the root bootstrap differs. The command previews add, replace, and conflicts by default. It checks manager.py, lifecycle.py, versions.py, systemx_paths.py, SYSTEMX.sh, SYSTEMX.ps1, INSTALL.sh, and INSTALL.ps1 against the new distribution and every intact retained release; customized or unrecognized files block the operation. A missing file is added only if no intact retained release ever contained it, such as versions.py in a genuine historical v1.5.0 install. A file that was present in a retained release but is missing now is a conflict. --apply saves byte-for-byte copies of replaced files under .SYSTEMX/.systemx/history/ and records an operation log. An add-only refresh has no original file to back up. The target must already be a managed installation. With a remote source, provide an exact --version; --archive-sha256 can independently pin that ZIP. Refreshed managed shell and PowerShell launchers invoke Python with -I -B. When invoking a reviewed external manager directly, use python3 -I -B /reviewed/new/.SYSTEMX/manager.py. First installation or adoption also rejects conflicting preexisting .py, .sh, and .ps1 defaults instead of treating them as trusted stock code. This manager installs and newly selects only releases 1.8.7-alpha.1 or newer. It can run an already selected, verified older snapshot through an isolated compatibility shim; its code and record behavior remain historical. Recovering an earlier release for selection requires a separately reviewed backup or legacy path, not a bootstrap-refresh rollback.

Removal and restore require the external library or a separate reviewed checkout, not a manager or current directory inside the folder being moved. The backup must be a new external path on the same filesystem. Preview makes no target changes; --apply is explicit. See first-time setup and uninstall, logs, and cleanup scope.

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.
validate --template	Also require reviewed blank records and only distribution files; inspect normally ignored folders for extras.
doctor	Report paths, Python version, available Git state, configuration, and executable availability.
paths or alias	Inspect canonical casing and lowercase path behavior; menu option 11
alias --create	Enable the local lowercase link; menu option 12
setup-guide	Print the first-time guide; menu option 13
removal-guide	Print uninstall/restore instructions; menu option 14
Menu option 15	Print the SYSTEMX PROJECTS guide
Menu option 16	List registered projects
Menu option 17	Print Agent X and Agent Z setup/review guides
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 current focus, shared context, master plan, project memory, selected agent notes, and relevant open-task summaries.
refresh-work	Regenerate six work views and CURRENT.md from valid canonical records.
task-ready	List TODO tasks with completed dependencies; optional --agent filters the registered owner.

doctor itself does not contact services or prove authentication. An opted-in managed launcher may check for updates before running it; use run --offline to prevent that startup check. 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. Use --template only for a pristine distribution. Real project records are expected to fail that extra check after adoption; use ordinary validate then.

Use exact .SYSTEMX paths in every command and prompt. Conflicting case variants stop execution before project writes. The case and alias guide explains safe recovery, old launchers, and the distinct internal version cache.

Select current focus

bash .SYSTEMX/SYSTEMX.sh focus --objective 'Finish the accepted outcome' --task TASK-001

--objective is required unless using --clear and allows up to 600 characters. Repeat --task for up to ten unique existing IDs. --checkpoint optionally names an existing Markdown file under MEMORY/sessions/, relative to .SYSTEMX. The command replaces the complete selection, so repeat every ID to retain. focus --clear accepts no selection fields and preserves tasks and checkpoints.

Current task status, next actions, and blockers are always read from the ledger. The focus timestamp records the selection, not a fresh runtime observation.

Prepare a worker packet

# Supply the source revision you have just observed.
bash .SYSTEMX/SYSTEMX.sh task-packet TASK-001 --base 'REPLACE_WITH_VERIFIED_REVISION'

Both the existing task ID and --base are required. The caller-supplied revision is recorded as context; this command does not verify it. The packet includes the task scope/acceptance, dependency summaries, and selected owner's memory, capped at 14,000 and 3,000 characters respectively with explicit truncation notices.

task-ready and task-packet are read-only and do not dispatch agents. Dependency readiness alone does not establish write-scope, resource, or permission readiness. A packet may describe blocked work for diagnosis; inspect the actual task state before dispatch. Use task-show for original dependency evidence and full detail.

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.

SYSTEMX PROJECTS

Run from the outer workspace root, or pass the same arguments through systemx run --target WORKSPACE -- projects ...:

bash .SYSTEMX/SYSTEMX.sh projects list
bash .SYSTEMX/SYSTEMX.sh projects add Project-A --kind software
bash .SYSTEMX/SYSTEMX.sh projects add Project-A --kind software --apply
bash .SYSTEMX/SYSTEMX.sh projects context --project Project-A --agent agent.0
bash .SYSTEMX/SYSTEMX.sh projects status --root
bash .SYSTEMX/SYSTEMX.sh projects refresh-status --project Project-A --apply
bash .SYSTEMX/SYSTEMX.sh projects validate --project Project-A
bash .SYSTEMX/SYSTEMX.sh projects validate
bash .SYSTEMX/SYSTEMX.sh projects check --project Project-A --dry-run
systemx export-chat --target WORKSPACE --project Project-A --output NEW_PACKET.md

task-add, task-set, task-show, task-ready, task-packet, focus, agent-add, and refresh-work accept their existing flags with --project NAME or --root under projects. Execution commands are check, dev, build, and deploy, with --dry-run available. Creation kinds are general, software, research, operations, and channel. validate without a selector explicitly checks every registered scope. No implicit project, source fetch, or agent launch occurs. See SYSTEMX PROJECTS for the complete contract.

Agent X and Agent Z

bash .SYSTEMX/SYSTEMX.sh roles-init
bash .SYSTEMX/SYSTEMX.sh roles-init --apply
bash .SYSTEMX/SYSTEMX.sh agent-x list --limit 25
bash .SYSTEMX/SYSTEMX.sh agent-x due --as-of 2026-10-05T00:00:00Z
bash .SYSTEMX/SYSTEMX.sh agent-z policy
bash .SYSTEMX/SYSTEMX.sh agent-z prepare --kind prompt --subject initial-prompt \
  --revision PROMPT_HASH --evidence-revision CONTEXT_HASH --stage planned --apply
bash .SYSTEMX/SYSTEMX.sh agent-z score R_RETURNED_ID --apply
bash .SYSTEMX/SYSTEMX.sh agent-z compare Z_PREVIOUS_ID Z_CURRENT_ID

Use the complete returned record IDs instead of placeholders. Preparation and scoring preview by default; --apply persists a request/report. Fill all 100 answers in the saved request before interpreting its score; unknowns are zero points, not automatic passes. Each child command uses projects agent-x COMMAND --project NAME or projects agent-z COMMAND --project NAME. projects roles-init also requires a scope selector. See Agent X for event/schedule flags and Agent Z for fixed-policy review, validation, report preservation, and delta rules.

Workflow concepts and transport boundaries

Phases and waves are planning conventions in the Master Plan; no phase, wave, cloud-sync, bot launcher, or automatic review-loop command is shipped. Use the existing task, focus, role, and project commands with an explicit scope. The one-shot guide and shared workspace guide show how an authorized harness or external adapter supplies execution/transport.