VisionOS Command Line Interface (CLI)

The visionos-cli package provides the visionos binary—a high-fidelity, interactive, and terminal-first educational environment. It guides users through hands-on learning tracks (Git, Linux, OS, React) with physical workspace analysis and real-time command syntax validation.

🚀 Installation & Setup

Installing Globally

To install the visionos CLI executable globally from npm:

npm install -g visionos-cli

Building & Installing Locally

To build and install the CLI from this monorepo directory:

# Navigate to monorepo root and execute build
npm run build

# Package the CLI into a tarball
npm run pack:cli

# Globally install the generated package tarball
npm install -g ./visionos-cli-*.tgz

Verify your installation by running:

visionos --version

🛠 Command Reference

visionos start

Starts a guided, interactive terminal-based learning session.

• Description: Boots the local embedded runtime (if stopped), handles session authorization checks, prompts you to select a learning track, handles resume state checkpoints, configures your practice directory, and launches you into the step-by-step interactive lesson runner.
• Interactive Engine Flow:
  1. Authentication Check: Verifies active session token. Launches browser sign-in if credentials are missing.
  2. Track Selector: Queries all available tracks from MongoDB (or local offline catalog fallback).
  3. Checkpoint Detection: Automatically detects your progress. Offers to Resume Last Lesson, Start from Beginning, or Browse Catalog.
  4. Workspace Choice: Prompts you to practice in the Default isolated sandbox or a Custom directory.
  5. Step Execution Loop: Prints lesson title, estimated minutes, step instructions, and expected result verification commands. Executes commands, displays real OS system stdout/stderr outputs, and intercepts typos or failed exit codes to render descriptive mistake cards.
• Usage:

  visionos start

visionos login

Authenticates the terminal with your cloud-backed learner account.

• Description: Spins up a local temporary embedded bridge server, launches your system browser to coordinate a secure MongoDB or Google authentication token handoff, and saves credentials under ~/.visionos/account.json and ~/.visionos/user.json.
• Options:
  • -t, --track <trackId>: Directly attach a specific learning track (e.g. git, linux, os-commands) to the browser login session to skip intermediate track prompts.
• Usage:

  visionos login
  visionos login --track os-commands

visionos lessons

Browse and preview the interactive track curriculum.

• Description: Lists all structured lessons, estimated completion times, and step counts for each learning path.
• Options:
  • -t, --track <trackId>: Filter and display lessons belonging exclusively to the specified track.
  • -l, --lesson <lessonId>: Directly preview details (steps, objectives, verification commands, and descriptions) for a specific lesson without starting it.
• Usage:

  # Interactive track search
  visionos lessons
  
  # View all lessons in the Git track
  visionos lessons --track git
  
  # Inspect a specific rebase lesson
  visionos lessons --lesson git-github-connect

visionos open

Instantly opens the VisionOS web learning dashboard.

• Description: Evaluates active local runtime parameters and opens the dashboard inside your default system browser. Automatically injects your local account credentials securely via one-time URL tokens so you bypass manual login screens.
• Usage:

  visionos open

visionos userinfo

Inspects and displays details about your locally stored learner profile.

• Description: Reads and formats cached session data, active progress tracks, authentication dates, and configuration folder structures.
• Options:
  • --json: Prints the entire structured learner profile, active paths, and runtime metadata as a raw JSON block (perfect for script hooks or advanced telemetry debugging).
• Usage:

  # Formatted terminal display
  visionos userinfo
  
  # Print machine-readable JSON
  visionos userinfo --json

visionos status

Show the embedded VisionOS runtime and connectivity status.

• Description: Runs a diagnostic inspect check on active local runtime configurations. Reports background process IDs (PIDs), target API server endpoints, web dashboard URLs, and authentication status.
• Usage:

  visionos status

visionos logout

Removes the locally stored VisionOS learner session.

• Description: Securely clears all cached profile states, local accounts, and session metadata from the ~/.visionos/ directory.
• Usage:

  visionos logout

💾 State & Sandbox Architecture

VisionOS operates with a highly robust system structure designed for sandbox isolation and hybrid data replication:

1. File Configuration Directory (~/.visionos/)

The CLI stores internal state and configurations in the user's home folder:

• ~/.visionos/account.json: Stores secure token parameters for API authorization.
• ~/.visionos/user.json: Caches core learner profile details (name, email, current track key).
• ~/.visionos/runtime.json: Keeps track of current local embedded server specifications (ports, endpoints, PIDs).
• ~/.visionos/progress.json: Stores local backup checkpoints for completed lessons/steps. Automatically synchronizes with the MongoDB remote server once internet connection is established.

2. Workspace Sandbox Isolation

When executing dynamic steps, learners are offered two practice directories:

• Default isolated sandbox (~/.visionos/sandbox/<lesson-id>): A completely secure, isolated repository rebuilt from scratch at every lesson boot. Bounded operations guarantee zero impact on your computer's home directory.
• Custom workspace directory: Allows learners to select a path of their choice on their system.

  [!IMPORTANT] When working inside a custom workspace, all clean/reset triggers are disabled. The CLI operates in a pure read-only inspection mode, ensuring none of your personal files are ever modified or deleted.

🔍 Validation Engine Modes

Every learning step defines a validation rule that is dynamically validated by the local parser without compiling TypeScript code:

• syntax Mode: The user runs the command. The engine runs it in the sandbox, captures real OS stdout/stderr, and confirms successful exit codes (exit 0). Intercepts errors (e.g. typos, options flags) to display rich troubleshooting mistake alerts.
• file-exists Mode: Scans the workspace to physically confirm folder or file creation rules.
• file-contains Mode: Inspects the file contents to verify exact characters, branch bindings, or repository commits exist.