Laintas CLI documentation

Get started

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

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.

Get started

Install

Requirements

Linux

The installer picks the binary that matches your CPU architecture:

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:

uname -m
getconf LONG_BIT
ldd --version

macOS

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 Helpwo Kernel.

Windows

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

The installer imports a private WSL 2 distribution named Laintas-CLI and installs a native laintas-cli.exe launcher. Your default WSL distribution is left alone, and normal startup does not run wsl.exe. You can choose the drive to install to.

Source package

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

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, Windows installer, 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.

Get started

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 platform documentation for how device authorization works.

Get started

Updating

Updates, the download page and the install scripts all read one channel: GitHub Releases. On Windows the CLI actually runs inside its private WSL distribution, so /v update replaces the Linux program there; the laintas-cli.exe launcher and the distribution itself are updated by re-running the installer, which keeps existing data.

Everyday use

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.

Everyday use

Sessions and context

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.

Everyday use

Models and usage

Models are billed by tier; a higher tier draws more units from the allowance per call. Which models are in each tier, and their prices, are on the pricing page.

Everyday use

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.

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.

Everyday use

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.

Everyday use

Plans, tasks and workflows

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.

Control and safety

Modes

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

Custom modes

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

/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:

{
  "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.

Control and safety

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

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.

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.

Control and safety

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.

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

Customise

Choosing a customisation surface

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

Customise

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.

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.

Customise

MCP servers

MCP suits tools that already run as a separate service or need their own dependency environment. Configure servers in ~/.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.

Customise

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.

Customise

Backends

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

• 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 (plugins)

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.

Sources and trust

Extensions (plugins)

Official extensions

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

/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.

Extensions (plugins)

Writing and publishing extensions

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

{
  "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.

Connect

Using it with Helpwo

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

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

Connect

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.

{"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.

Reference

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

Account and session

Agents and terminals

Planning and tasks

Configuration and tools

History

Reference

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 platform 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.

Files not found on Windows

The CLI runs inside its private WSL distribution, where Windows drives are mounted under /mnt/<drive>/ — C:\Users\me\project is /mnt/c/Users/me/project.

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.