Docs
⌘K

Command line

One command signs you in through your browser, installs the agental command and the agent skills, and opens a shell in a new sandbox.

For your agent

agental.io/docs/cli.md
shell
npx agental@latest sh

It needs Node.js 20.16 or later, and OpenSSH for the shell. What it does, in order:

  • It opens your browser at agental. Sign in or sign up there, and allow your computer. The command is given an API key of its own, named CLI on <your computer>, and keeps it in ~/.config/agental/credentials.json, which only you can read.
  • It installs the agental command with npm install -g agental, or updates an older one.
  • It installs the agent skills for the coding agents it finds on your computer, with npx skills add https://agental.io -g.
  • With sh, it makes a sandbox named sh- and six hex digits, on your default template at its size, and opens a shell in it over SSH.

Leave the shell with exit. The sandbox goes on running, and is billed by the second, until you stop it: the command says what an hour of it costs, and how to stop it. A stopped one keeps its disk and costs 5% of its running price.

TipThe browser sends its answer only to the command on the computer the browser is on, so nobody else can catch it. Allow it only when you ran the command yourself, just then.

Next time

On a computer that is signed in, nothing is asked and no browser opens. npx agental@latest sh makes another sandbox, and agental ssh <id> opens a shell in one you have. Without sh it checks the command and the skills are up to date, and lists what to run next. Delete the computer's key in the console, under API keys, and the next run signs in again.

Run by an agent

With no terminal to type into, as when a coding agent runs it, the browser still opens on your screen, and the command waits ten minutes for you to allow it. Then it makes the sandbox and, in place of a shell, prints agental exec <id> -- <command> and agental ssh <id> -- <command>. With --json it prints the sandbox as JSON, and everything else on standard error.

At your plan's limit

No sandbox is made. In a terminal it offers to open your newest running sandbox instead: press Enter. Otherwise it lists your sandboxes, running ones first, and ends with an error. Stop one with agental stop <id>, or delete it with agental delete <id>. Where a plan is needed first, it gives the Billing page.

Signing in

CommandWhat it does
agental loginSigns in through the browser, as above.
agental login --keyReads a key from standard input, and keeps it. For a computer with no browser, such as a server you reach over SSH: make the key in the console, under API keys.
agental whoamiWho the command is signed in as, and with which key. --json for a program.
agental logoutDeletes this computer's key from your account, and the file it was kept in. A key that was pasted in is left in your account.

AGENTAL_API_KEY, when it is set, is used in place of the kept key, and AGENTAL_API_URL names another API. The TypeScript and Python SDKs use the kept key too when they are given none, for the API it was made for and no other. With AGENTAL_NO_BROWSER set, the command prints the address to open and opens nothing.

Options

OptionWhat it does
--no-installLeaves the agental command as it is.
--no-skillsLeaves the agent skills as they are.
--jsonPrints the sandbox as JSON on standard output.
Nextagental help lists every command: templates, secrets, files over SSH, the desktop, the browser, metrics, webhooks, billing and more.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]