Laintas CLI documentation

Installing, everyday use, modes and the security policy, extending it, and a full command reference. Written for the latest release; /help shows what your installed version has.

Overview

Laintas CLI puts an ordinary interactive shell and an AI agent runtime in the same terminal. Type a command and it runs as it always would; type a sentence and the agent inspects the workspace, calls tools, runs commands and continues from the results until the task is done.

How each line is handled

InputWhat happensModel involved?
Starts with /A built-in or extension command, handled locallyNo
First word is a program on PATH or a shell builtinRuns directly in the main terminal term0, like any terminal: live output, keyboard input, and Ctrl+C interrupts only that command; Ctrl+] detaches it and /fg brings it backNo
Anything elseBecomes a task for the agent: an observable, interruptible tool-use loopYes

What it is for

  • Fixing bugs, running tests and changing configuration inside a repository — the agent sits next to the files and the terminal, so there is nothing to copy back and forth.
  • Server operations: reading logs, inspecting processes, editing an nginx config — with every command checked by the security policy.
  • Long-running work: named sub-terminals, several agents in parallel, resumable workflows.

Account and billing

The CLI itself is free. With the official Laintas backend, AI calls are paid from your Laintas account — allowance, trial calls or balance. See the account and billing documentation.

Install

Helpwow windows desktop edition

For Helpwow chat, editor, preview and agents in a Windows desktop window, download Helpwow windows, formerly laintas-Helpwo-cli-for-windows. It uses local workspace files and terminals by default; see the Helpwow windows guide. The laintas-cli-windows described below is a separate terminal product.

Requirements

PlatformRequirementsPackage
Linux x86_6464-bit, glibcStandalone binary, no Python needed
Linux aarch6464-bit ARM, glibcStandalone binary, no Python needed
macOS Apple Silicon / Intelarm64 / x86_64Native terminal binary, no Python needed
WindowsWindows 10 2004+ or Windows 11, 64-bitlaintas-cli-windows installer with its own terminal window
Anything else (Alpine/musl, 32-bit …)Python 3.10+Source package

Linux

The installer picks the binary that matches your CPU architecture:

bash
curl -fsSL https://cli.laintas.com/install.sh | bash
laintas-cli

If you are unsure the machine is compatible, check the architecture, word size and glibc version first:

bash
uname -m
getconf LONG_BIT
ldd --version

macOS

bash
curl -fsSL https://cli.laintas.com/install.sh | bash
laintas-cli

The installer chooses the Apple Silicon or Intel archive, verifies its SHA-256 checksum and installs to ~/.local/bin. The Mac build does not include Helpwow Kernel.

Windows

PowerShell
irm https://cli.laintas.com/install.ps1 | iex

Run the command in PowerShell to download the latest laintas-cli-windows installer, verify its size and SHA-256 and open it. Run $env:LAINTAS_INSTALL_SILENT=1 first to skip the wizard. You can also download it directly.

Download laintas-cli-windows beta v5, open the installer (no administrator rights needed), then launch laintas-cli-windows from Start.

laintas-cli-windows is the same Laintas CLI in a terminal window of its own: it needs no WSL and does not use the Windows console, so the interface, colors and keys match Linux and macOS. Commands run in the bundled bash environment, where drives appear as /c/Users/.... It requires Windows 10/11 x86_64 and WebView2; the installer can download WebView2.

Beta and SmartScreen

This is the first beta and the installer is not code-signed yet, so Windows may say it protected your PC on first run. Choose "More info → Run anyway"; to be sure the file is ours, compare it with the SHA-256 checksum.

The sign-in page opens in your default browser, and links in the window open with Ctrl+click. Ctrl+C copies when text is selected and interrupts otherwise; Ctrl+V pastes. Account data is kept in .laintas in your user profile and survives a reinstall.

Source package

For platforms without a standalone build, or when you want to audit, debug or modify the CLI:

bash
unzip laintas-cli_source.zip
cd laintas-cli-source
python3 -m pip install -r requirements.txt
python3 laintas_cli.py

Linux and macOS archives for both architectures, the Debian package, source package and SHA-256 checksums are published on GitHub Releases and mirrored at cli.laintas.com/releases/latest/; the download section offers an installer that picks the Linux or Mac architecture automatically.

First run and sign-in

  1. 01Run laintas-cli in the directory you want to work in. The directory it starts in is the agent’s workspace.
  2. 02The first start prints an authorization link. Open it in a browser on any device, sign in to your Laintas account and approve.
  3. 03The CLI finishes signing in by itself and shows its prompt. Type a command or a task to begin.

The session is stored in ~/.laintas/session.json, readable only by your user. See the account and billing documentation for how device authorization works.

CommandEffect
/loginSign in again, e.g. to switch accounts
/quit, /qExit and keep the session
/exitSign out and exit

Without a Laintas account

The CLI can also talk to a model endpoint of your own (see Backends). A loopback backend needs no sign-in, and calls to a custom backend are not billed by Laintas.

Updating

CommandEffect
/vShow the installed version
/v checkCheck for a newer release
/v updateDownload and install the latest release; --force reinstalls even when the version matches

/v update reads cli.laintas.com/releases/latest/ on every platform. The laintas-cli-windows window and runtime are updated by the installer: download the new installer and install over the old one.

Giving the agent a task

Describe the outcome you want in plain language — for example "run the tests and fix the one that fails". The agent reads files, runs commands and edits code step by step, and every step is shown in the terminal.

  • Add to it — type a new instruction while a task runs; the agent sees it at its next step.
  • Interrupt — press Esc to stop the current task (this works while the model is thinking; a tool already running finishes first). A single Ctrl+C is ignored during a run; pressing it twice quickly force-exits the CLI.
  • Approve — an action that needs approval pauses and asks you to approve or reject it. Modes and the security policy decide what needs approval.
  • Why did it fail — /why explains the most recent tool failure; /detail on records full execution detail for each turn, browsable later with /detail trace.
  • Context — /prop shows the exact context and system prompt sent to the model for a turn.

Project instructions

Write the repository’s conventions — test commands, code style, directories to leave alone — in .laintas/cli.prop at the project root. It is appended to the project instructions every turn. It is plain text and executes nothing.

Memory and rules

/memory manages facts kept across sessions (global and per-project), and /rule manages constraints to follow every time. Both take up context every turn, so keep them short. They guide behaviour; they do not grant or remove permissions — use modes and the security policy for that.

Sessions and context

CommandEffect
/newStart a new session (alias /clear)
/resume [N|all|latest]Open the session picker and switch to a saved session, without creating a branch
/fork [name]Branch an independent session off the current context
/compactCompact the current context now; /compact status shows thresholds and the background worker
/toldReplay earlier prompts or one agent’s conversation

When the context reaches 70% of the usable budget, the CLI starts compacting in the background; at 90% the agent waits for that result or compacts in the foreground. Messages you type meanwhile are preserved. The --resume and --continue flags at startup behave like /resume.

One session, one terminal

A session that is open in another terminal cannot be resumed at the same time. Switch away from it or close that terminal first.

Models and usage

CommandEffect
/modelList available models and choose one for this terminal; /model reset restores the default
/model auxChoose the model used for auxiliary work such as compaction summaries
/usage [7d|30d|90d]Local token statistics plus usage and allowance from your Laintas account
/usage buy calls|storageBuy a credit pack or storage

A tier (T0–T5) says how strong a model is; the price is each model's own. Paid from balance, a call is charged the balance price on the pricing page; paid with member credits, it draws the member price in credits — far less for most models. Per-model prices are on the pricing page.

Terminals and sub-terminals

The main terminal is term0. Put long-running programs — dev servers, log tails, interactive REPLs — in named sub-terminals. They survive across tasks, and the agent sees their latest output every turn.

CommandEffect
/tOpen the terminal browser: n new, e enter, o observe, x twice to close
/term <name>Create a named sub-terminal; /term rename <old> <new> renames one
/backReturn from a sub-terminal to its parent; the child keeps running
/send <name> <command>Send input to a terminal; --wait <seconds> waits for output
/terminate <name>Close a terminal and everything under it
/bash <command>Run one command through term0

Inside a sub-terminal, Ctrl+\ force-detaches. When running under tmux, interactive programs open natively in a new tmux window.

Commands you type run attached to term0, which needs a real terminal and bash 4.4+ or zsh; where there is no terminal to attach to (pipes, the /agents view), they fall back to running one at a time and showing the output when done.

Multiple agents

One CLI process can hold several persistent agents ("employees"). Each has its own conversation, terminals, model and tool policy; the working directory, project memory and tool registry are shared.

CommandEffect
/hire [name]Hire an agent, optionally with --profile, --model, --tools, --terminal; hiring does not start any work
/agent <name>Switch the foreground conversation to that agent; work it finished in the background is kept
/agentsFull-screen view of every agent’s activity; Enter sends an update to a working agent or a new task to an idle one
/spawn [name:] <task>Spawn a sub-agent for a subtask
/tell <agent> <message>Send a message to an agent
/abort <agent>Abort an agent
/stationLive manager for agents and terminals: assign work, bind terminals, preview routing

Permissions never widen

Sub-agents and auto-routed work run inside their parent’s permissions; role selection and routing never grant more tools than the parent has. Automatic writing tasks require Git worktree isolation.

Plans, tasks and workflows

CommandEffect
/plan enter <task>Enter plan mode: the agent explores read-only and writes a plan; it executes only after you revise and approve it
/taskProject task list: add, start, finish, subtasks, progress
/retaskOpen the checklist of work the AI handed to you (Alt+R)
/workflowMulti-phase workflows: each phase has its own tool scope and is advanced and approved in turn
/hwo <file>Run an HWO orchestration file: live collaboration between agents
/hwg <file.hwg>Compile and run an HWG graph workflow: durable and resumable, /hwg resume continues after an interruption
/workInspect or resume unified work-graph state

Git checkpoints

/snapshot [label] creates a checkpoint, /snapshots lists them, and /undo [sha] restores one. Taking a checkpoint before a wide-ranging change is a good habit.

Modes

A mode sets the agent’s working posture — which tools it may use and what is approved automatically. Switch with /mode <name>.

ModeUse
actDefault; normal execution
reviewRead-only code and design review; the workspace is not modified
studyRead-only; listens and writes what matters to memory
autoAutonomous execution; actions that need confirmation get a timed confirmation window
stepRuns one model iteration at a time; press Enter (/continue) to advance

Custom modes

Create a read-only documentation review mode from the command line:

laintas-cli
/mode create docs-review --tools "fs.read,fs.grep,fs.glob" --deny "shell.*,fs.write,fs.edit" --auto-approve none

Or declare it in the project’s .laintas/modes.json:

.laintas/modes.json
{
  "version": 1,
  "active": "docs-review",
  "modes": {
    "docs-review": {
      "description": "Review documentation without modifying the workspace",
      "instructions": "Check correctness, structure, examples, and broken references.",
      "allowed_tools": ["fs.read", "fs.grep", "fs.glob"],
      "denied_tools": ["shell.*", "fs.write", "fs.edit"],
      "auto_approve": "none"
    }
  }
}
  • denied_tools wins over allowed_tools; tool names accept glob patterns.
  • auto_approve is one of none, writes, commands, all.
  • A mode can only narrow: the effective tool set is intersected with the workflow phase, role, global policy and trust state, so a mode cannot re-open what another layer denies.

Security policy

Every command the agent wants to run goes through the policy engine first and gets one of three decisions: allow, needs_approval or deny. Every decision is written to an audit log.

Policy modes

ModeBehaviour
audit (default)Deny rules apply; ordinary approval rules only log a warning; the high-risk actions below still always ask
enforceEvery approval rule pauses for confirmation, including sudo and writes outside the workspace
disabledTurns policy checks off. Requires --yes; only for a throwaway, isolated environment

Always asked, in audit and enforce alike

  • Delete commands — including deletes wrapped in bash -c "…" and similar shells.
  • Destructive git: reset --hard, clean -fdx, push --force, branch -D, stash drop and the like.
  • Commands that read keys, cookies, tokens or a credential store. Reading credentials and sending them off the machine in the same command is denied outright.
  • Unbounded recursive walks outside the working directory.

Decisions are made on the parsed command, not only on the typed string: extra spaces, quote splicing, wrapper commands and similar obfuscations are resolved before matching.

File / commandNotes
~/.laintas/policy.jsonThe rules (allow / needs_approval / deny regex lists). Safe defaults are written on first load; edits apply without a restart
~/.laintas/audit.logJSONL audit log, one line per decision, rotated at 10 MB
/policy [audit|enforce|disabled|reset]Show or switch the policy mode; reset restores the default rules

Project trust

Executable project files — .laintas/commands.py, .laintas/loop.py and project extensions — run only after you approve the hash of their current content with /trust allow. Any change invalidates the approval and needs a fresh review, so cloning an unfamiliar repository cannot make its code run silently in your CLI. /trust status shows the state; /trust revoke removes it.

Configuration and files

/config shows every runtime setting; /config <key> <value> changes one; /config export <file> and /config import <file> move settings between machines. /theme dark|light|mono switches the colour scheme.

LocationContentsScope
~/.laintas/config.jsonRuntime preferencesUser
~/.laintas/session.jsonSign-in state (private)User
~/.laintas/policy.jsonGlobal command and tool policyUser
~/.laintas/backends.jsonBackend profiles and credential referencesUser
~/.laintas/mcp.jsonMCP server definitionsUser
~/.laintas/hooks.json, hooks.pyLifecycle hooksUser
~/.laintas/skills/, extensions/User-installed skills and extensionsUser
~/.laintas/memory/, sessions/, agents/Memory, sessions and agent dataUser
.laintas/cli.propProject instructionsProject
.laintas/memory.json, rules.jsonProject memory and rulesProject
.laintas/modes.jsonCustom modesProject
.laintas/commands.py, loop.py, extensions/Executable project customisation (trust required)Project

Private files and directories are created with restrictive permissions; executable project customisation rejects symlinks and unsafe ownership.

Choosing a customisation surface

Use the narrowest surface that solves the problem — the ones that execute no code need no trust approval.

NeedUseRuns code?
Change general behaviour/configNo
Add project instructions.laintas/cli.propNo
Keep facts or constraints/memory, /ruleNo
Restrict tools for a way of working.laintas/modes.jsonNo
Reusable guidanceSkill SKILL.mdNo
A small project command.laintas/commands.pyYes (trusted)
Reusable in-process toolsSkill skill.pyYes (trusted)
An external tool serverMCPChild process (trusted)
Commands, tools and lifecycleExtensionYes (signature or hash trust)
Intercept runtime eventsHooksDepends
Another inference endpointBackend profileRemote service

Skills

A skill is a directory under ~/.laintas/skills/<name>/. Only the short front matter of SKILL.md is indexed at startup; the full instructions load when the skill is used, and references load on demand — so many skills cost neither startup time nor context.

Layout
my-skill/
├── SKILL.md          # name, description, version, instructions
├── references/       # loaded only when the skill needs them
├── skill.py          # optional: get_tools()
└── extension.json    # required when skill.py provides tools

A skill with only SKILL.md runs no code. A skill with skill.py provides tools; it must declare its capabilities in extension.json and pass hash trust before it is registered. A user skill overrides a bundled skill of the same name. Manage skills with /skill.

MCP servers

MCP suits tools that already run as a separate service or need their own dependency environment. Configure servers in ~/.laintas/mcp.json:

~/.laintas/mcp.json
{
  "servers": {
    "example": {
      "command": "/absolute/path/to/example-server",
      "args": ["--stdio"],
      "env": {"EXAMPLE_TOKEN": "..."},
      "cwd": "/absolute/path/to/workspace",
      "enabled": true,
      "call_timeout": 30,
      "capabilities": ["fs.read"]
    }
  }
}
  • Tools appear in the unified registry as mcp.<server>.<tool>.
  • Child processes get a minimal environment plus the variables you configure explicitly.
  • Trust is bound to the hash of the server configuration: changing how it launches requires a fresh review.
  • Manage servers with /mcp list, /mcp connect, /mcp tools and /mcp trust.

Hooks

Hooks observe or gate runtime events: command and tool execution, session start and end, errors, memory changes and more.

  • Declarative hooks (~/.laintas/hooks.json) run a program as an argument vector — no shell — with the event JSON on standard input, and support conditions, timeouts and block_on_failure.
  • Python hooks (~/.laintas/hooks.py) are in-process callbacks with more power; they require executable trust.

Declarative hooks are enough for audit forwarding and deterministic checks; use Python only when the event genuinely needs local program logic. A hook configured to block fails closed. Manage hooks with /hooks.

Backends

Backend profiles in ~/.laintas/backends.json divide inference endpoints into three trust domains. Manage them with /backend.

DomainMeaning
officialExact Laintas origins; may receive your Laintas session and bills your account
customAn HTTPS endpoint you name, with its own credential reference (env:VARIABLE or keyring:service/user); not billed by Laintas
localA loopback development endpoint; no authentication and no Laintas sign-in
  • A custom endpoint cannot declare itself official.
  • Laintas credentials are never sent to a custom host, and a custom token is never sent to an official origin; authenticated requests do not follow cross-origin redirects.
  • Never put secrets in a URL or in a file you commit.

Extensions and the plugin market

Extensions are not part of the CLI itself: each is installed separately, its commands and tools appear only once it is, and they go away when it is removed. Browse official and community extensions in the plugin market.

CommandEffect
/extensions available [official|community]Browse the market
/extensions search <keyword>Search official and community extensions
/extensions install <source>Install an extension (source formats below)
/extensions listList extensions installed on this machine
/extensions info <name>, remove <name>Show details, uninstall

Sources and trust

SourceInstall withTrust
Official/extensions install laintas/<name>Official registry hash plus your explicit approval
Community/extensions install @author/<name>Immutable package hash, a fresh static check and AI source review on every install, and your explicit approval
Local/extensions install <path-or-url>Content hash plus your explicit approval

Community extensions are not sandboxed

The AI review is advisory: community Python still runs with your user’s permissions. Critical findings block installation and a failed scan stops it, but confirm you trust the author before every install.

Official extensions

Maintained and published by Laintas. They too are installed by hand; none ships with the CLI.

ExtensionCommandWhat it does
laintas/ai-pow/powA process score and verifiable work journal for every Git commit
laintas/blindpick/blindpickRun the same task with two models on isolated branches, compare blind, apply only the one you pick
laintas/canvas/canvasWhiteboards in the terminal: view and draw .excalidraw boards, and let the agent draw on them
laintas/swebench/swebenchGenerate SWE-bench predictions with the CLI; scoring stays with the official harness
laintas/whatsapp/whatsappSend the CLI a task over WhatsApp; it runs it and reports back
Example
/extensions install laintas/blindpick
/blindpick

For how to use an extension, run /help <command> after installing it, or see its card in the plugin market.

Writing and publishing extensions

An extension is the broadest customisation unit: it can register slash commands, tools, loop handlers and teardown logic.

extension.json
{
  "schemaVersion": 2,
  "name": "example",
  "version": "0.1.0",
  "entrypoint": "main.py",
  "description": "Example Laintas extension",
  "author": {"name": "Your Name"},
  "license": "MIT",
  "toolPrefix": "example."
}
  • main.py exports setup(ctx); the context offers narrowed registration and backend-call helpers, and official sign-in credentials are never handed to the extension.
  • toolPrefix must be lower-case and end with a dot.
  • Project extensions live in .laintas/extensions/<name>/, global ones in ~/.laintas/extensions/<name>/; a project extension shadows a global one of the same name.
  • /extensions create scaffolds a package, /extensions pack builds a .lext, and /extensions publish <name> publishes to the community registry. Community packages cannot use the laintas publisher namespace.
  • /evolve lets the agent generate, test and hot-load an extension for the current project, with rollback.

Using it with Helpwow

Helpwow is an AI workspace in the browser. The CLI can make its machine a runtime environment for Helpwow, or run Helpwow locally.

CommandEffect
/helpwo --remoteBring this machine online as a Helpwow runtime environment: on helpwow.laintas.com you can browse its files, open terminals and let the AI run commands here
/helpwoRun Helpwow locally in a sub-terminal named helpwo; the current folder is its workspace, and sign-in, data and conversation are kept per folder
/helpwo stopClose the Helpwow sub-terminal and everything in it
/sharedShare files with Helpwow through Laintas storage (push / pull / list)

In remote mode, file contents travel peer-to-peer between the browser and this machine, not through Helpwow’s servers. For the Helpwow side, see the Helpwow docs.

Hosted applications

/app runs a registered application in its own sub-terminal with a dedicated agent. Manifests live in ~/.laintas/apps/*.json or ./.laintas/apps/*.json; each must be trusted with /app trust <name> before it starts, and again after it changes.

Manifest
{"name": "notes", "description": "…", "command": "node server.js",
 "app_url": "http://127.0.0.1:3000",
 "prompt": "What this app's agent is for.", "persistence": "none", "port": 8123,
 "session_tools": ["shell.exec"], "auto_approve": false,
 "max_sessions": 10, "session_idle_minutes": 30}

An application can ask for an isolated session per user — its own sub-terminal and agent. The CLI provides the isolation; users, billing and protocol are the application’s to define.

Where isolation ends

Every session runs as the operating-system user running the CLI. Separate homes keep agents from loading each other’s data; they do not stop a shell command from reading another folder. If end users are untrusted and have shell.exec, run the CLI in a container or under a dedicated account.

Command reference

These are the CLI’s built-in commands. /help lists everything in your installed version, including commands from installed extensions (see Official extensions); /help <command> shows one command’s usage.

Basics

CommandDescription
/help [command]Command help
/cwdShow the working directory
/fgReturn to a command detached with Ctrl+]
/messagesRead your Laintas inbox (alias /msg)
/scanList user-facing commands on PATH
/img <path> [question]Read an image: ask about it or transcribe it

Account and session

CommandDescription
/loginSign in again
/usageAI usage: local token stats plus your Laintas usage; buy buys calls or storage
/resume, /fork, /newSwitch, branch or start sessions
/quit, /exitExit keeping the session / sign out and exit
/backDetach from a sub-terminal
/vVersion and updates
/passwordLocal password vault
/trainingTraining-data sharing (cloud) and local capture
/extensionsInstall, manage and publish extensions

Agents and terminals

CommandDescription
/name [new-name]Show or set the current agent’s name
/hire, /agent, /agentsHire, switch to, and overview agents
/spawn, /tell, /abortSpawn a sub-agent, message one, abort one
/stationAgent and terminal manager (alias /st)
/term, /send, /terminateCreate, feed and close terminals (/t opens the terminal browser)
/helpwo, /app, /sharedHelpwow, hosted applications, shared files
/handoffHand work to the next person as a file

Planning and tasks

CommandDescription
/mode, /planModes and plans
/task, /retask, /workTask list, work handed to you, work graph
/workflow, /hwo, /hwgMulti-phase workflows, orchestration, graph workflows
/promptPrompt Lab: tested prompt overlays
/evolveGenerate, test and hot-load project extensions

Configuration and tools

CommandDescription
/model, /config, /theme, /streamModel, settings, colours, streaming preview
/policy, /trust, /hooks, /backendSecurity policy, project trust, hooks, backends
/webWeb search and fetch: engines, proxy, cookies, diagnostics (alias /search)
/identitySaved logins the agent may browse as
/tools, /tool <name>List tools, call one directly
/skill, /mcpSkills, MCP servers
/memory, /propMemory, inspect the full context
/debug, /why, /detailDebug entries, explain a failure, execution detail
/maxLift runtime limits for this process

History

CommandDescription
/snapshot, /snapshots, /undoGit checkpoints
/compact, /continue, /toldCompact, continue, replay
/reloadReload default files and restart

Troubleshooting

A call is refused over balance or allowance

Nothing is charged for these refusals. The codes and what to do about each are in the account and billing documentation. Check your allowance with /usage.

It looks stuck

  • Check whether it is waiting for an approval: in auto mode approvals have a timed window; other modes wait for your answer.
  • The command itself may be long-running — a find over a large tree, say. Press Esc and give a narrower scope.
  • Near the context limit it compacts first; /compact status shows whether that is running.

Reporting a problem

When filing an issue on GitHub, include the version from /v, your operating system and the relevant /why or /debug output — with anything sensitive removed. Account and billing questions go to the Laintas contact page.