365Soft Docs
Main Site

CLI Guide

Detailed reference for install, workflow, and troubleshooting.

Install

macOS / Linux

curl -fsSL https://labs.365softlabs.com/cli/install.sh | sh

Windows (PowerShell)

iwr https://labs.365softlabs.com/cli/install.ps1 -useb | iex

Demo Workflow

365soft demo run --repo https://github.com/acme/app --task "Add careers form CV validation for PDF and DOCX only"
365soft demo status --run-id <RUN_ID>
365soft demo approve --run-id <RUN_ID> --step plan
365soft demo approve --run-id <RUN_ID> --step apply_patch
365soft demo approve --run-id <RUN_ID> --step pr

Sprint Planning

Create a sprint plan artifact with goals and owners:

365soft sprint plan --sprint-id sprint-2026-03 --goals "Lock scope;Implement handoff flows;Ship docs" --owners "orchestrator,frontend,backend"

Formatting rules:

  • --goals uses semicolon separators (Goal A;Goal B;Goal C).
  • --owners uses comma separators (planner,backend,tester).
  • --sprint-id should be stable and searchable (for example sprint-2026-03).

This creates:

  • artifacts/sprints/<sprint_id>/sprint.json
  • artifacts/sprints/<sprint_id>/SPRINT-PLAN.md

Recommended flow:

  1. Create sprint plan with goals and owners.
  2. Create run(s) scoped to individual sprint outcomes.
  3. Issue orchestrator handoffs per role.
  4. Track completion notes and approvals before merge.

Orchestrator to Agent Handoff

Create, complete, and list handoffs linked to a run:

365soft handoff create --run-id <RUN_ID> --role planner --message "Break task into implementation units"
365soft handoff complete --run-id <RUN_ID> --role planner --summary "Work breakdown completed"
365soft handoff list --run-id <RUN_ID>

Supported roles:

planner, frontend, backend, tester, reviewer, devops

By default, handoff notes are appended to:

  • C:\code\_agent-instructions\HANDOFF.md
  • C:\code\_agent-instructions\TASK-COMPLETE.md

How handoff lifecycle works:

  1. Orchestrator writes a handoff message for a role.
  2. Assigned role executes task using its own role instructions.
  3. Role writes completion summary when done.
  4. Orchestrator verifies state and creates next handoff or gate approval.

Reference files used by role orchestration:

  • C:\code\_agent-instructions\AGENTS.orchestrator.md
  • C:\code\_agent-instructions\AGENTS.planner.md
  • C:\code\_agent-instructions\AGENTS.backend.md
  • C:\code\_agent-instructions\AGENTS.frontend.md
  • C:\code\_agent-instructions\AGENTS.tester.md
  • C:\code\_agent-instructions\AGENTS.reviewer.md
  • C:\code\_agent-instructions\AGENTS.devops.md

Optional override:

# PowerShell
$env:AGENT_INSTRUCTIONS_DIR="D:\agent-instructions"

Capability MCP Preflight

Before planning a capability, verify required MCP servers are available:

365soft capability check --capability "xai docs" --suggest-offline

If MCP servers are missing, the CLI returns:

  • missing server names
  • Codex config.toml snippet(s)
  • Claude MCP settings snippet(s)
  • offline reference fallback command

Where CLI checks MCP config by default:

Codex Config Check Paths

  • <current-project>\.codex\config.toml
  • %USERPROFILE%\.codex\config.toml
  • $env:CODEX_CONFIG_PATH (if defined)

Claude Config Check Paths

  • <current-project>\.claude\settings.json
  • <current-project>\.claude\config.json
  • %USERPROFILE%\.claude\settings.json
  • %USERPROFILE%\.claude\config.json
  • %USERPROFILE%\.claude.json
  • C:\code\_agent-instructions\.claude\settings.json

If your files are in custom locations, set CODEX_CONFIG_PATH for Codex or keep a canonical team config under C:\code\_agent-instructions.

MCP Config Snippets

Codex config.toml:

[mcp_servers.xaiDocs]
url = "https://docs.x.ai/api/mcp"

Codex formatting requirements:

  • Section name must be [mcp_servers.<serverName>].
  • Server name is case-sensitive in team conventions (use xaiDocs).
  • Use valid TOML (quotes around URL, one key-value per line).

Claude MCP settings JSON:

{
  "mcpServers": {
    "xaiDocs": {
      "url": "https://docs.x.ai/api/mcp"
    }
  }
}

Claude formatting requirements:

  • Top-level key is mcpServers.
  • Each server entry must include a valid url.
  • Ensure strict JSON syntax (double quotes, no trailing commas).

Offline Reference Build

If MCP is unavailable, capture local documentation via existing scraper scripts:

365soft offline-reference plan --target <business-docs-profile>
365soft offline-reference build --target <business-docs-profile> --manual-login

365soft offline-reference plan --target <developer-docs-profile>
365soft offline-reference build --target <developer-docs-profile> --manual-login

What the CLI does for offline reference:

  1. Resolves target to existing scraper script and seed list.
  2. Builds exact Node command with required arguments.
  3. Runs Playwright-based capture flow when you execute build.
  4. Stores output as date-stamped snapshots and manifests.

Current script mapping:

  • <business-docs-profile> -> C:\code\_agent-instructions\offline_reference\scripts\<capture-script>.mjs
  • <developer-docs-profile> -> C:\code\_agent-instructions\offline_reference\<capture-script>.mjs

Expected output structure:

  • ...\offline_reference\YYYY-MM-DD\manifest.json
  • ...\offline_reference\YYYY-MM-DD\SUMMARY.txt
  • ...\offline_reference\YYYY-MM-DD\pages\*.html|*.txt|*.png|*.meta.json

Output is stored under C:\code\_agent-instructions\offline_reference\....

Per-Agent Instruction Setup

Role behavior is controlled by central instruction files and AGENTS includes. Role-specific Codex TOML templates are not used.

Core instruction root:

C:\code\_agent-instructions

Role instruction files:

  • AGENTS.orchestrator.md
  • AGENTS.planner.md
  • AGENTS.backend.md
  • AGENTS.frontend.md
  • AGENTS.tester.md
  • AGENTS.reviewer.md
  • AGENTS.devops.md

The switch helper updates the project AGENTS.md include to point to the selected role file, then launches the agent.

Claude role assets:

  • .claude\agents\*.md
  • .claude\settings.mcp.example.json

Agent switching helper:

C:\code\_agent-instructions\switch-agent.ps1 -Role orchestrator -Launch

Tips and Tricks

  • Keep tasks specific and testable.
  • Use clear branch names (feat/..., fix/...).
  • Use status between approvals to validate current gate.
  • Track each run_id in tickets for traceability.

Troubleshooting

365soft command not found

  • Restart terminal.
  • Ensure install directory is in PATH.
  • Re-run installer.

Port Already In Use (Local API)

This means the default API port (8787) is already being used by another process, so the demo API cannot start on that port.

Find and stop the process using port 8787:

netstat -ano | findstr :8787
Stop-Process -Id <PID> -Force

Or start the API on a different port:

$env:PORT="8788"
npm run demo:api

Demo UI cannot connect to API

  • Start API server first from C:\code\365softlabs-cli.
  • Check health endpoint http://localhost:8787/health.
  • Set MVP_API_BASE_URL if using non-default API location.

Security Notes

  • Never commit access tokens.
  • Use environment variables and secret management.