5. CLI entry points
[!ref] Full details in the User Manual, "Download, run and system requirements".
The CLI version shares sessions and config with the desktop; they can hand work back and forth.
5.1 Main subcommands
The desktop main binary (AVLCode, AVLCode.exe on Windows) has built-in terminal entry points:
| Command | Purpose |
|---|---|
AVLCode tui |
Launch the TUI in your terminal, sharing sessions with the desktop |
AVLCode zagent-tui |
Launch the batch-mode conversation TUI; useful for scripting |
The consolidated CLI binary (zBoxFull) provides five service entry points:
| Command | Purpose |
|---|---|
zBoxFull zWorkspace |
Workspace service |
zBoxFull zAgent |
One-shot LLM conversation (JSONL batch) |
zBoxFull zSkill |
Skill management and signing (SM2/SM3) |
zBoxFull zChannel |
Companion messaging (standalone / dry-run / callback mode) |
zBoxFull zMCP |
External tool service debug |
zBoxFull install |
Install symlinks for the five service entry points into a chosen directory; afterwards call them by short name, e.g. zWorkspace |
tui/zagent-tuiare built into the desktop main binary; no separate zBoxFull install needed.
5.1.1 TUI launch flags
| Flag | Meaning |
|---|---|
--config <path> / -c <path> |
Provider config file path; when omitted, resolved from ZAGENT_PROVIDER_CONFIG, then the bundled default config |
--session <ID> |
Resume the given session (records are read back and replayed). Empty = generate a new session ID; if the named session is missing or corrupt, a notice is printed and a new session is opened under that same ID (your naming intent is preserved) |
5.1.2 TUI keys
| Key | Action |
|---|---|
| {{kbd:Enter}} | Send |
| {{kbd:F2}} | New session |
| {{kbd:Esc}} / {{kbd:Ctrl+C}} | Running: abort the agent; idle: quit |
| {{kbd:y}} / {{kbd:a}} / {{kbd:n}} | While a hook approval is pending: allow once / allow always (written to the workspace approvals file, recognised by the desktop app too) / deny. {{kbd:Esc}} = n; auto-denied after 30 seconds |
5.1.3 TUI built-in commands
All of these are handled locally and never sent to the model as an ordinary message.
| Command | Args | Description |
|---|---|---|
/goal |
[<goal> | budget <N> | pause | resume | complete | clear] |
Session goal, same source of truth as the desktop app; no args = show the current goal |
/compact |
[N] |
Compact history; optionally keep the last N messages verbatim. The compaction snapshot is persisted with the session and survives /resume |
/sessions |
none | List the 10 most recent sessions in the current workspace (newest first; the current one is marked *). Read-only |
/resume |
<session ID> |
Switch to the given session. The ID may not contain *?[]/\; on failure the current session is left completely untouched and only an error line is printed |
/login |
<user> / <user> <password> / phone <number> |
Sign in. No args prints usage; the <user> form takes the password on the next {{kbd:Enter}} (not echoed, not added to chat history); phone uses an SMS code, and when risk control kicks in the image captcha is saved as a PNG whose path is shown in the status bar |
/sso |
[paste <url>] / [cancel] |
SSO sign-in: starts a local callback listener and prints the authorisation URL; if the browser cannot bounce back, paste the URL manually with paste; cancel aborts |
/logout |
none | Sign out |
/usage |
none | Show usage and available credits (sign-in required) |
/redeem |
<code> |
Redeem a voucher code (sign-in required) |
/feedback |
<text> |
Submit feedback (sign-in required) |
/attach |
[<path> [ro|rw]] |
Session-level sandbox attachment. No args = list the current attachments (read-only; works in degraded mode too); relative paths resolve against the workspace root; mode defaults to ro; re-attaching the same path overrides its mode |
/detach |
<path> |
Detach that path |
/attach and /detach reject the same things the desktop app does: a path that does not exist, the filesystem root, and paths inside the workspace. Attachment pushes are unavailable in external / no-toolchain mode.
A startup announcement banner is fetched and shown on launch. The status bar always shows the available keys and commands, with toolchain status on the right.
5.2 Common args
| Arg | Meaning |
|---|---|
| `--workspace <id | path>` |
--config <path> |
Explicit config directory |
--log-level <level> |
error / warn / info / debug |
--no-color |
Disable colour output |
-h / --help |
Help |
-V / --version |
Version |
5.3 Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Generic error |
| 2 | Argument error |
| 64 | Config error |
| 65 | Data error |
| 69 | Service unavailable |
| 70 | Software error (please report) |