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

> ## Agent Instructions
> Praesia is in closed beta. Cards work in the sandbox with test funds, and no real money moves. To use Praesia, you need an invite. To request an invite, open https://praesia.ai/contact.

# Praesia CLI command reference

> Every praesia command and its options.

| Command | What it does |
| - | - |
| [`praesia request`](#praesia-request) | Asks for the sign-in link of an agent |
| [`praesia call`](#praesia-call) | Runs one tool |
| [`praesia profiles`](#praesia-profiles) | Lists the agents on this machine |
| [`praesia doctor`](#praesia-doctor) | Checks the profile of an agent |
| [`praesia operations`](#praesia-operations) | Lists the payments whose outcome isn't known yet |
| [`praesia serve`](#praesia-serve) | Starts the server for the harness |
| [`praesia server-command`](#praesia-server-command) | Prints the command that starts the server |

## `praesia request`

Prints the sign-in link of an agent and its expiry on standard error, then exits.

```bash theme={"theme":"material-theme-darker"}
praesia request --name NAME [--profile NAME] [--invite CODE] [--json]
```

| Option | What it does |
| - | - |
| `--name` | The agent's name, up to 160 characters |
| `--profile` | The profile of the agent |
| `--invite` | Your invite code |
| `--json` | Prints the link and its expiry as one object on standard output |
| `--help` | Prints the usage |

Until you approve the agent, the same command gives the link again, and only the newest link counts. It takes no limit, currency or merchant: those come from the [mandate](https://docs.praesia.ai/mandates.md).

## `praesia call`

Runs one tool. On standard output, it prints the tool's text, a blank line, then the structured result as one line of JSON. It exits 1 when the result carries an error flag. Otherwise it exits 0, even for a payment whose outcome isn't known yet.

```bash theme={"theme":"material-theme-darker"}
praesia call TOOL [--profile NAME] [--arguments JSON]
```

| Option | What it does |
| - | - |
| `--profile` | The profile of the agent that acts |
| `--arguments` | One JSON object that holds the tool's arguments. `-` reads it from standard input. |
| `--help` | Prints the usage, or a tool's description with `praesia call TOOL --help` |

> [accordion] Rules for the arguments
>
> * A tool that takes only `agent` takes no `--arguments`.
> * The object leaves out `agent`, or gives the same profile name as `--profile`.
> * The command refuses an object with a repeated key.
> * With `-`, use a quoted heredoc. Put the object on one line, and use a new closing word each time.

> [accordion] The structured result
>
> The result holds the sentences of its text in `sentences`, its first member, word for word. A JSON line after the sentences stays out of `sentences`. A read whose text is only JSON, such as `get_mandate`, has no `sentences`.

> [accordion] When the command refuses
>
> | Situation | What the command does |
> | - | - |
> | An unknown tool, invalid JSON, or an argument the tool doesn't take | It refuses. |
> | Before `praesia request` | It lists the agents on this machine, and names `praesia request` when there is none. |
> | After `praesia request`, before your approval | It prints `Enrollment pending. Run praesia call get_status.` and the sign-in link. Only `get_status` with only `agent` runs. |
>
> Two tools have no command. `enroll` is replaced by `praesia request`, and `list_agents` by `praesia profiles`.

## `praesia profiles`

Prints one line for each profile that holds a badge. It takes no option.

```bash theme={"theme":"material-theme-darker"}
praesia profiles
```

```text theme={"theme":"material-theme-darker"}
"AGENT_NAME" (organization "ORGANIZATION_NAME", profile PROFILE_NAME)
```

With no such profile, it prints `No agent on this machine holds a badge.` If a profile can't be read, it prints one line on standard error that names `praesia doctor`, and exits 1.

## `praesia doctor`

Checks the profile of an agent. It prints a line that starts with `Doctor passed` or `Doctor failed`, which gives the reason. A profile that can't start prints its refusal instead.

```bash theme={"theme":"material-theme-darker"}
praesia doctor [--profile NAME]
```

## `praesia operations`

Lists the idempotency key and the state of each payment whose outcome isn't known yet. It names `get_status` with that key as the next call.

```bash theme={"theme":"material-theme-darker"}
praesia operations [--profile NAME]
```

A listed payment hasn't failed, so don't send it with a new `idempotency_key`.

> [accordion] States and messages
>
> | State or message | What it means |
> | - | - |
> | Pending | The call ran out of time. |
> | Unresolved | The payment answered `result: "unresolved"`. |
> | `No pending or unresolved operations are recorded.` | The list is empty. |
> | `This machine keeps no record of payments. Call get_status with the idempotency key of each payment.` | The CLI can't write its Praesia home. |

## `praesia serve`

Starts the one server of the machine for the harness. It takes no `--profile`.

```bash theme={"theme":"material-theme-darker"}
praesia serve [--call-budget-ms MS]
```

| Option | What it does |
| - | - |
| `--call-budget-ms` | The budget of each tool call in milliseconds. The minimum is 1000. The default is 20 seconds, and 40 seconds for `draft_mandate`. Keep it below the tool call limit of your harness. |

## `praesia server-command`

Prints the absolute command that starts the server. The output is one line of JSON with `command` and `args`. It takes no option.

```bash theme={"theme":"material-theme-darker"}
praesia server-command
```

## Profiles

Each agent has its own profile in the Praesia home. Every agent on the machine uses the same server entry.

A profile name has at most 64 characters. It starts with a letter or a digit, then uses letters, digits, dots, underscores and hyphens. For example: `office-supplies`.

`request`, `call`, `doctor` and `operations` take the profile from `--profile`, then `PRAESIA_PROFILE`, then `default`. `serve`, `server-command` and `profiles` take no profile.

> [accordion] When a profile name is wrong
>
> | You send | Praesia answers |
> | - | - |
> | A tool call with no `agent`, or with a value that isn't a profile name | A refusal that names `agent` and `list_agents` |
> | An `enroll` call with no `agent`, or with a value that isn't a profile name | A refusal that gives the rule for a new profile name |
> | A tool call or `praesia call` for a profile that isn't on the machine | A refusal that lists the agents on the machine |

## Environment variables

An empty value counts as unset.

| Variable | What it sets | Default |
| - | - | - |
| `PRAESIA_HOME` | The Praesia home, which holds the profiles | `~/.praesia` |
| `PRAESIA_PROFILE` | The profile of `request`, `call`, `doctor` and `operations` with no `--profile` | `default` |


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