Skip to content
LangAlphaLangAlphaLangAlpha Docs

The LangAlpha CLI

langalpha is LangAlpha’s command line. It starts and follows threads, answers the agent’s questions and approvals, and manages workspaces, computers and automations, all against the same server the web app talks to. It is made for three kinds of caller: a person at a terminal, a script, and the agent inside one of your computers, where every computer already has it.

The current release candidate is 0.1.0-rc.1.

Install

Section titled “Install”

The CLI is published to npm as langalpha and needs Node.js 20 or later.

Terminal window
npm install -g langalpha@next
langalpha --version

Name the next tag: until the first stable release the CLI ships as a prerelease, and npm’s default latest tag does not carry it yet. The package puts both langalpha and la on your PATH.

Build it from source

Section titled “Build it from source”

To run the code on LangAlpha’s main line, or to change it, build the cli/ folder of the LangAlpha repository. It needs Node.js 20 or later and pnpm.

Terminal window
git clone https://github.com/ginlix-ai/langalpha.git
cd langalpha/cli
pnpm install
pnpm build              # writes dist/la.mjs, one file with no dependencies
node dist/la.mjs --help

To run it by name, make the file executable and link it onto your PATH under both names:

Terminal window
chmod +x dist/la.mjs
ln -s "$PWD/dist/la.mjs" ~/.local/bin/langalpha
ln -s "$PWD/dist/la.mjs" ~/.local/bin/la

Two names: langalpha and la

Section titled “Two names: langalpha and la”

langalpha is the full name and la the short one. Both run the same program.

Many shells already alias la to ls (oh-my-zsh does, and so does Ubuntu’s default .bashrc), and an alias wins over a program. If la --version lists files instead of printing a version, type langalpha, or command la to skip the alias. The usage lines and hints the CLI prints name la only when that is what you typed, so they always show a command that works in your shell.

Inside a computer the agent’s commands run without your aliases, so la is safe there. These docs write langalpha throughout.

How commands are shaped

Section titled “How commands are shaped”

A command is a group, an action, its operands, then options:

Terminal window
langalpha threads send <id> <message...> [-m MODEL] [--wait] [--detach]
  • Each command accepts exactly the options it declares, plus the global options below. Anything else is refused as a usage error, so a typo never swallows the next word as its value.
  • An option takes its value as the next word or after =: --limit 5 and --limit=5 are the same.
  • A last operand written <message...> takes every remaining word, so a message needs no quotes unless your shell would read something in it. Put -- before a message that starts with a dash.
  • Global options may come before the command’s words, as in langalpha --server http://localhost:8000 threads list.
  • langalpha threads on its own lists that group’s commands, and langalpha <command> --help prints one command’s options.

Wherever a command takes a workspace (-w WS, <ws>), WS is a workspace id, its exact name, or home for Home. A name is matched exactly across all your workspaces. If no workspace has it the command exits with code 4, and if two do it asks for the id.

Global options

Section titled “Global options”

Every command takes these.

Option What it does
--server URL The LangAlpha server to talk to. Without it, LANGALPHA_URL, then the server you last signed in to, then http://localhost:8000.
--token T A token for this one call, ahead of every other credential.
--json Machine-readable output. A command prints one JSON value; a turn’s stream prints one JSON event per line; an error goes to stderr as {"error", "status", "detail"}.
-h, --help Show the commands, or one command’s options.
--version Print the version.

Output

Section titled “Output”

Without --json, lists print as aligned tables with the columns most worth reading, and a cell longer than 60 characters is cut short. --json prints every field the server returned, whole. Text that comes from the server or the agent is stripped of terminal control characters before it is shown, so a thread title cannot rewrite your terminal.

A delete asks for confirmation at a terminal. With no terminal attached, as in a script, it is refused unless you pass --yes.

Exit codes

Section titled “Exit codes”

Exit codes are part of the CLI’s contract, so scripts and agents can act on them.

Code Meaning
0 Success.
1 An error: the server could not be reached, the stream closed before the turn ended, or the server failed.
2 A usage error: a missing operand, an unknown option, or a request the server rejected as invalid (400 or 422).
3 Not signed in, or not allowed (401 or 403).
4 Not found (404).
5 Conflict (409), for example approving a thread that is not waiting for an answer.
6 The turn is waiting for an approval or an answer. See threads approve.
7 The turn failed or was cancelled.

Commands

Section titled “Commands”
Group Commands
Sign-in login, logout, whoami
Computers list, add, start, stop, remove
Workspaces list, create, archive, delete
Threads list, show, new, send, follow, retry, approve, reject, cancel, archive, delete
Automations list, create, edit, trigger, pause, resume, delete
Models list
Section titled “Related”