@holoscript/holoscript-cli

The unified user-facing agent CLI for HoloScript. Single global install, single user-visible binary: holoscript.

npm i -g holoscript
holoscript            # opens REPL
holoscript --tools    # REPL with MCP tool calling enabled

What this package is (and is not)

This is the agent CLI — REPL, gateway daemon control, channel adapters, and identity. It is not the HoloScript compiler.

| Binary | Purpose | Package | |--------|---------|---------| | holoscript | Agent CLI (REPL, gateway, channels, whoami, status) | @holoscript/holoscript-cli (this package) | | hsc | HoloScript compiler (was holoscript pre-v0.1) | @holoscript/cli | | hs | Compiler alias (preserved muscle memory) | @holoscript/cli | | aibrittney | Workspace-local REPL package | @holoscript/aibrittney (wrapped by this CLI) | | holoscript-agent | Headless daemon runtime | @holoscript/holoscript-agent (wrapped by holoscript gateway) |

If you previously typed holoscript build foo.holo to compile a scene, that is now hsc build foo.holo (or hs build foo.holo). The agent CLI took the canonical name because the agent IS the user-facing surface — compilation is one capability among many that the agent dispatches.

Status (v0.1)

This is the A.1 scaffold of the staged execution plan. The package compiles, dispatches subcommands, and wraps the existing aibrittney REPL. Subcommand bodies are placeholders pending A.2 (configure, whoami, status) and A.3 (gateway install / autostart / installer scripts).

| Feature | Status | Lands in | |---------|--------|----------| | holoscript (REPL via aibrittney) | wired | A.1 | | holoscript --tools | wired | A.1 | | holoscript --version / --help | wired | A.1 | | holoscript configure | placeholder | A.2 | | holoscript gateway install | placeholder | A.3 | | holoscript gateway autostart enable\|disable\|status | placeholder | A.3 | | holoscript gateway start\|stop\|status | placeholder | A.3 | | holoscript channels enable <name> | placeholder | (deferred — channel adapters not in A series) | | holoscript whoami | placeholder | A.2 | | holoscript status | placeholder | A.2 |

Design principles

1. Single user-visible bin: holoscript

The compiler bin renamed to hsc to free holoscript for the agent CLI. The hs alias stays on the compiler side so existing compiler-CLI users don't lose muscle memory.

Grounded in the project vision:

• npm i -g holoscript should do what new users expect — open an agent.
• the agent IS the surface; compilation is an internal capability.
• Architecture beats alignment: namespace conflicts are resolved structurally, not by hoping users remember.

2. Autostart is OFF by default

holoscript gateway install installs the gateway binary + config but does NOT register a login-item, LaunchAgent, or systemd unit. Autostart requires explicit opt-in:

holoscript gateway install                       # binary + config only
holoscript gateway autostart enable              # explicit consent for OS-startup
holoscript gateway autostart status              # show current registration state
holoscript gateway autostart disable             # remove from OS-startup

Grounded in the project vision:

• Silent always-on processes that touch auth are hostile by default.
• F.001 (key handling): no auth surprises.
• Production is the product: consent-first installs.

A vitest test in __tests__/no-startup-mutation.test.ts pins this contract from day one.

Build

pnpm --filter @holoscript/holoscript-cli build
pnpm --filter @holoscript/holoscript-cli test