# The LangAlpha CLI

> langalpha, or la for short, runs your threads, workspaces, computers and automations from a terminal, a script, or the agent inside a computer. How to install it and how its commands behave.

Source: https://docs.langalpha.ai/cli/overview/

`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](https://docs.langalpha.ai/concepts/computers/), where every computer already has it.

The current release candidate is 0.1.0-rc.1.

## Install

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

```sh
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

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.

```sh
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:

```sh
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

`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

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

```sh
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](https://docs.langalpha.ai/concepts/workspaces/#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

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

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

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](https://docs.langalpha.ai/cli/threads/#threads-approve). |
| `7` | The turn failed or was cancelled. |

## Commands

| Group | Commands |
| --- | --- |
| [Sign-in](https://docs.langalpha.ai/cli/auth/) | `login`, `logout`, `whoami` |
| [Computers](https://docs.langalpha.ai/cli/computers/) | `list`, `add`, `start`, `stop`, `remove` |
| [Workspaces](https://docs.langalpha.ai/cli/workspaces/) | `list`, `create`, `archive`, `delete` |
| [Threads](https://docs.langalpha.ai/cli/threads/) | `list`, `show`, `new`, `send`, `follow`, `retry`, `approve`, `reject`, `cancel`, `archive`, `delete` |
| [Automations](https://docs.langalpha.ai/cli/automations/) | `list`, `create`, `edit`, `trigger`, `pause`, `resume`, `delete` |
| [Models](https://docs.langalpha.ai/cli/models/) | `list` |

## Related

- [Signing in](https://docs.langalpha.ai/cli/signing-in/)
- [Using the CLI inside a computer](https://docs.langalpha.ai/cli/inside-a-computer/)
- [Scripting recipes](https://docs.langalpha.ai/cli/scripting/)
- [HTTP API](https://docs.langalpha.ai/api/overview/)