Skip to main content
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.

Run it

The CLI needs Node 22 or later. Run it with npx, which runs the newest release:
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

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

Read its output from a script

Add --json to any command to print its result as 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:
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.