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 withnpx, 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:.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:
--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 tohttps://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:.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.