CLI and Tools

CLI and Tools

Page 2 of the four-part 4K field guide separates management CLI/local launchers, app-native workers, Agent Y's external CLI lane, project checks and Agent 0/X/Y/Z responsibilities. The refreshed artwork also connects ROOT rules/planning and observed SYSTEMX/harness/optional bot TODOs: read-only delta informs an authorized reconciliation and readback. Page 3 adds on-demand AGENTA context; page 4 shows the shared outer tools and selected child records.

.SYSTEMX is the shared project format. The optional systemx CLI selects reviewed defaults and routes record operations; your AI app, IDE, shell, Git, cloud tools, and explicitly configured commands provide execution. Agent Y adds a separate task-selected provider process when another installed CLI is useful. These entry points have distinct responsibilities and contexts.

The core CLI/project commands began in 1.9.0-alpha.5; AUTOBOT/Agent Alpha and DATA commands require 1.10.0-alpha.2 or compatible newer defaults. Install or select a compatible reviewed release before using them. The current wiki can change; a release's START-HERE.md and local guides remain the fixed instructions for that release. See Installation and updates, Command reference, and the portable CLI/tools guide.

Choose the entry point

Entry point	What it does	What you must select
systemx / python -I -B -m systemx	Installed library/management CLI: install, pins, audit, backups, selected-default run, child routing, chat export	Explicit outer project --target; a reviewed Python environment
bash .SYSTEMX/SYSTEMX.sh	Local shell launcher for a reviewed folder copy or a managed installation	Correct outer working directory; compatible trusted defaults
powershell -File .SYSTEMX/SYSTEMX.ps1	Local PowerShell launcher with the same record/menu interface	Exact .SYSTEMX path; an allowed existing execution environment
App / IDE tools	Native worker/subagent creation, file changes, tool calls, permission and process controls	Authorized task, scope, files, budget, and harness capability
Configured project tools	check, dev, build, deploy, doctor inspections	Explicit argument arrays in the selected scope's project.json; inspect --dry-run
Agent Y provider CLI	One bounded separately selected Codex, Copilot, or configured provider run	Existing task, provider, repository, base, packet, paths, budget, and PR policy
Git and GitHub CLI (gh)	Repository state/worktrees and authorized PR operations used by Agent Y	Actual repository/account and recorded lifecycle authority
Drive/cloud/connector tools	Authorized access and snapshot transport	Real access, one record owner, conflict handling, saved revision/readback

For an unmanaged folder copy, review the local source and invoke its own launcher. The external manager's run and projects commands require a valid managed installation. Existing INSTALLATION.json state is validated; an invalid file, conflicting path, directory, or dangling marker must stop execution rather than silently falling back to local code. Shell/PowerShell support is a local entry point, not evidence that all native platforms or external providers were tested.

The local command tools-guide and menu option 18 print the portable CLI/tools guide. They do not install, log in to, or launch a provider. Menu 15 displays SYSTEMX PROJECTS, menu 16 lists registered children, and menu 17 displays the role guides. Use Exact casing and alias for .SYSTEMX naming.

Start with one explicit installation

# Inspect tool and installation; these are different versions.
systemx --version
systemx status --target "/path/to/workspace"

# Inspect selected workspace records and the command map.
systemx run --target "/path/to/workspace" --offline -- status
systemx run --target "/path/to/workspace" --offline -- tools-guide

# Reviewed local copy or managed launcher from its outer working directory.
bash .SYSTEMX/SYSTEMX.sh tools-guide
bash .SYSTEMX/SYSTEMX.sh doctor
bash .SYSTEMX/SYSTEMX.sh check --dry-run

systemx status describes installation metadata. The runtime status describes the selected task ledger. doctor reports observed tools/configuration and cannot prove logins, service access, or deployment health. check --dry-run prints the configured argument arrays without running the checks. An explicitly permitted check executes those tools and returns their actual exit status; deploy requires the existing project/service authority and a reviewed target.

Python tools require Python 3.9+ and use the standard library. Prefer a maintained interpreter. Installing the optional package does not provision Git, gh, provider CLIs, cloud accounts, an application stack, MCP, or a scheduler. Review your existing toolchain before configuring commands. See Stack Guide, Configuration and quality, and Library integration.

Select a .SYSTEMXP child with shared outer tools

workspace/
└── .SYSTEMX/                         one installation and selected default version
    ├── SYSTEMX.sh / SYSTEMX.ps1      reviewed local launchers
    ├── scripts/ / manager.py         shared runtime and management tools
    ├── GLOBAL/ / PLAN/ / WORK/       outer coordination records
    ├── Projects/REGISTRY.json        explicit child identities
    └── Projects/
        ├── Project-A/.SYSTEMXP/     A context, plan, tasks, agents, evidence
        └── Project-B/.SYSTEMXP/     B context, plan, tasks, agents, evidence

A child .SYSTEMXP holds records. It has no nested .SYSTEMX, independently installed CLI/default cache, or recursive projects tree. The command --target is the directory containing the outer .SYSTEMX; --project is the registered child identity. For example:

# Preview creation; apply is a separate explicit step.
systemx projects --target "/path/to/workspace" -- add Project-A --kind software
systemx projects --target "/path/to/workspace" -- add Project-A --kind software --apply
systemx projects --target "/path/to/workspace" -- list
systemx projects --target "/path/to/workspace" -- context --project Project-A --agent agent.0
systemx projects --target "/path/to/workspace" -- status --project Project-A
systemx projects --target "/path/to/workspace" -- check --project Project-A --dry-run
systemx projects --target "/path/to/workspace" -- context --root --agent agent.0

The direct projects command defaults offline. --online only permits an eligible advisory startup metadata check under the installed policy; it does not download/select defaults, ignore the pin, contact recorded source URLs, or sync a child. --offline suppresses only startup release discovery; explicitly run project commands, providers, Git, or gh may still access the network. Put manager flags before -- and scoped subcommand arguments after it. The compatibility form remains:

systemx run --target "/path/to/workspace" --offline -- projects context --project Project-A
bash .SYSTEMX/SYSTEMX.sh projects context --project Project-A

Scoped operations require --project NAME or --root. Listing is inherently an outer registry operation, and unselected projects validate deliberately checks all registered scopes. Top-level runtime operations continue to address outer records. Configured child commands execute from .SYSTEMX/Projects/Project-A, beside the selected records; an external source path does not silently change that working directory. Choose explicit command arguments for that layout. IDs and agent memory are local to each child; include the project name in handoffs. See SYSTEMX PROJECTS.

Agent Y is a separate external provider lane

# Preview scoped role activation, then inspect installed providers.
systemx projects --target "/path/to/workspace" -- roles-init --project Project-A
systemx projects --target "/path/to/workspace" -- agent-y providers --project Project-A

Agent 0 assigns an existing scoped task to agent.y and records its packet, allowed files, actual repository/base, provider/model choice, cost/concurrency limits, and acceptance criteria. Preparation pins the selected executable path, raw hash, and file identity. Agent Y returns a task-owned worktree and scoped commit, plus a draft PR only when separately opted in. Agent 0 independently checks the original criteria; X records observed event/time/revision/evidence; Z reviews a matching policy and subject. Agent Y's CLI does not inherit an app's chat automatically, and its lifecycle does not merge a PR.

Accepted done enables a separately requested ready transition. Recorded cancellation enables close while preserving unmerged work. Cleanup requires an externally verified merge, acceptance, exact owned head, and retained archive. The provider runs with its host account's access; path/PR gates are not OS isolation. Native Windows Agent Y execution remains disabled in this alpha. Read Agent Y before any applied provider/PR command and Security and support for the remaining boundaries.

Keep a reproducible operational record

Record the selected installation/defaults version, outer target, child selector, actual working directory/repository, command/provider identity, observed revision, original output, and relevant timestamps. Save accepted results to the selected ledger and generated views; keep private sidecars and credentials out of public history. Preview explicit operations before applying them, retain backups, and verify the saved state after transport or recovery. A URL or a diagram grants no access and starts no process.

Full-system infographic · Command reference · Tool configuration · Agent 0 · Agent X · Agent Y · Agent Z · SYSTEMX PROJECTS

Tier 2 detail from an explicit Tools step

AUTOBOT and Agent Alpha adds a selected local detail request, not a new execution provider. A Tools step, including an integration's step 7, can deliberately invoke its documented commands with the selected root or child. Agent 0/X/Y/Z may request relevant Brand, Design, Rules, Research, or other panel detail for a task. Keep one canonical task ledger and the same host permissions. Neither a document read nor a saved request launches a bot.

Use data init to preview missing local DATA scaffolds, data init --apply to create them additively, and data audit to inspect the actual Git exclusion policy and tracked payloads. In a child, route the same command through projects data ... --project NAME. Raw payloads are not included in default context, request packets, or a recursive validation scan.

See the two guides for exact commands and scope rules. Agent Alpha activation is separate from roles-init; adding X/Y/Z never silently enables a Tier 2 role.

ROOT planning and a bounded tool-card contract

The optional ROOT layer needs compatible 1.11.0-alpha.1 defaults. It records request/structure references, actual harness/bot bindings, and timestamped observations. root delta compares the recorded mappings with canonical task state; it does not call an external API or set a task done. root init previews missing records and --apply adds them without replacing project files. Child use is projects root ... --project NAME or explicit --root.

ROOT/SX-MILESTONE.md describes a generic tool card: selected scope/request/task, advertised tool/capability, reviewed inputs, expected effect, actual permissions, revision/evidence requirements, and stopping condition. The app/IDE/CLI supplies the real tool name, schema, consent, and execution result. A card starts no process and grants no access. Existing Agent Y, project commands, Agent X, Agent Z, and AGENTA retain their own roles and explicit invocation boundaries.

root card previews a bounded handoff and explicit --apply saves it; neither form invokes the named tool. Use the exact flags in the command reference. root-guide and menu option 21 print the selected defaults' guide without initializing records or starting a provider.

root delta defaults to the harness layer; explicitly repeat --layer harness --layer bot when both real surfaces apply. Omitted layers are not_assessed. The report defaults to ten tasks and exposes selection coverage/truncation; its optional --limit maximum is 100. root packet supplies a bounded selected-work handoff of at most ten tasks and 64 KiB. Mapped external-item state/freshness is checked across all its bound tasks, including members outside that selection.

The 1.11.0-alpha.2 patch checks ROOT limits against the final rendered UTF-8 response before persistence, rather than a smaller intermediate representation. Agent Y's ROOT/AUTOBOT coordination guard preserves historical handoff scopes for inspection while blocking protected legacy jobs from execution/readiness. See ROOT output limits and Agent Y migration.