> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ambral.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# The ambral CLI

> Run it, sign in, choose the org it acts in, read its output from a script, and install the skill.

`ambral` is how you use Ambral from a terminal, and how your coding agent uses it for you. Every command, with
its arguments, flags and examples, is in the [command reference](https://docs.ambral.ai/cli/reference/global-flags.md).

## Run it

The CLI needs Node 22 or later. Run it with `npx`, which runs the newest release:

```sh theme={null}
npx ambral@latest --help
```

`ambral --help` lists every command, and `ambral <command> --help` describes one, with its arguments, flags and
examples.

The commands on these pages are written as `ambral …`. Where `ambral` isn't installed, run each as
`npx ambral@latest …`.

## Sign in

```sh theme={null}
ambral login
```

`ambral login` signs you in through your browser. It prints a link and a code, opens the link, and waits. Check
that the page shows the same code, then approve the sign-in.

Outside a terminal, as when a coding agent runs it, and with `--json`, `ambral login` prints the link and the
code and returns at once. `ambral login --wait` then waits until you approve or deny the sign-in. A new sign-in
replaces the one the CLI holds only once you approve it.

`ambral whoami` shows the account you're signed in as, the address the CLI talks to, and the org commands act
in. `ambral logout` signs you out.

Your sessions are kept in `$XDG_CONFIG_HOME/ambral/sessions/`, which is `~/.config/ambral/sessions/` unless you
set it, in files only you can read.

## Choose an org

Commands act in the org your project is linked to. List your orgs, then link the project to one by its slug:

```sh theme={null}
ambral orgs list
ambral orgs use <slug>
```

The link is `.ambral/project.json` in your project's root. The `.ambral` folder ignores itself in git, so the
link is never committed.

To act in another org for one command, add `--org <slug>`:

```sh theme={null}
ambral workloads list --org <slug>
```

## Read its output from a script

Add `--json` to any command to print its result as JSON:

```sh theme={null}
ambral workloads list --json
```

A command that fails exits 1. It prints what went wrong to stderr, and on the next line what to run next, when
there is something to run. With `--json` the failure is JSON too, on stdout, as an `error` object with a
`_tag` that names the failure, a `message` and a `remedy`. A `remedy` of `null` means the message says it all.

A command the CLI can't read, with an unknown subcommand or a flag or argument it doesn't take, is different. It
prints the command's help to stdout and the mistake to stderr, as text even with `--json`, and exits 1.

`ambral runs export` is the exception. Its output is a file's contents, so its failures go to stderr with
`--json` too.

## Use another address

The CLI talks to `https://app.ambral.ai`. To use an Ambral at another address, set `AMBRAL_URL`. Each address
keeps its own sign-in and its own project links.

## Install the skill

The skill teaches a coding agent how to use Ambral with this CLI. Install it from your project's root:

```sh theme={null}
npx ambral@latest skill install
```

It writes one copy to `.claude/skills/ambral/` for Claude Code, and one to `.agents/skills/ambral/` for other
agents that read Agent Skills. Each copy is stamped with the version of the CLI that wrote it. After that, any
`ambral` command run in the project by a newer CLI installs the skill again, so it stays matched to the commands
that CLI has.

If the install created `.claude/skills/`, a Claude Code session that was already open needs `/reload-skills` to
load the skill.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.