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

# CLI reference

> Reference for the formae command-line interface: global flags, the command index, and links to every command.

The formae CLI is the client you use to drive the [formae agent](/documentation/concepts/architecture).
It parses your command, sends a request to the agent over its REST API, and renders
the result. Most commands are asynchronous: `apply` and `destroy` submit work and
return. On an interactive terminal they show a live progress view by default;
otherwise they return immediately and you follow progress with [`formae status`](/documentation/reference/cli/status).

<Note>
  The formae CLI is being revamped on a feature branch. This reference documents the
  shipping behavior. The authoritative, always-current source for any command's
  options is the CLI's own help:

  ```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
  formae --help
  formae <command> --help
  ```
</Note>

## Command index

| Command                                               | What it does                                                                                          |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [`apply`](/documentation/reference/cli/apply)         | Create or update infrastructure from a forma (see [apply modes](/documentation/concepts/apply-modes)) |
| [`destroy`](/documentation/reference/cli/destroy)     | Tear down resources from a forma or a query                                                           |
| [`eval`](/documentation/reference/cli/eval)           | Evaluate a forma and print the resolved result without applying it                                    |
| [`extract`](/documentation/reference/cli/extract)     | Pull existing resources into a forma file                                                             |
| [`inventory`](/documentation/reference/cli/inventory) | List resources, stacks, targets, and policies                                                         |
| [`status`](/documentation/reference/cli/status)       | Query the agent and past commands                                                                     |
| [`cancel`](/documentation/reference/cli/cancel)       | Cancel in-progress commands                                                                           |
| [`agent`](/documentation/reference/cli/agent)         | Start and stop the agent                                                                              |
| [`plugin`](/documentation/reference/cli/plugin)       | Search, install, update, and scaffold [plugins](/documentation/concepts/plugin)                       |
| [`profile`](/documentation/reference/cli/profile)     | Manage named configuration [profiles](/documentation/reference/configuration)                         |
| [`project`](/documentation/reference/cli/project)     | Scaffold a forma project                                                                              |
| [`update`](/documentation/reference/cli/update)       | Manage the formae binary version                                                                      |
| [`clean`](/documentation/reference/cli/clean)         | Clean up old software versions                                                                        |

## Global flags

These flags are available on the root command:

| Flag              | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `-h`, `--help`    | Show help for formae or any command.                          |
| `-v`, `--version` | Show the formae version and the Go version it was built with. |

## Common flags

Commands that talk to the agent share a common set of flags.

### Choosing a configuration

Every agent-connecting command accepts a way to pick which configuration to use.
`--config` and `--profile` are mutually exclusive.

| Flag               | Description                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `--config <path>`  | Path to a config file to use for this command.                                           |
| `--profile <name>` | Named profile to use. See [`formae profile list`](/documentation/reference/cli/profile). |

With neither flag, formae uses the active profile. See [Configuration](/documentation/reference/configuration)
for how profiles are stored and selected.

### Shaping the output

Commands that return data accept flags to switch between human and machine output.

| Flag                                 | Default | Description                                                |
| ------------------------------------ | ------- | ---------------------------------------------------------- |
| `--output-consumer <human\|machine>` | `human` | Whether output is formatted for a person or for a machine. |
| `--output-schema <json\|yaml>`       | `json`  | The schema used for machine output.                        |

On an interactive terminal, `apply`, `destroy`, and `cancel` show a live status
view by default and exit when the work completes. Press `q` to detach at any
time; the command keeps running on the agent. Off a TTY (piped, CI, or machine
output) they are fire-and-forget: they return a command ID and you follow
progress with [`formae status`](/documentation/reference/cli/status). The
`status` commands accept `--watch` to continuously refresh until completion.

## Queries

Several commands accept a `--query` flag to select resources, targets, or
commands by their attributes. Queries are space-separated `key:value` terms, and
`*` works as a wildcard anywhere in a value (for example `foo*`, `*foo`, `*foo*`,
or `foo*bar`).

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae inventory resources --query 'type:AWS::S3::Bucket stack:prod'
formae status command --query 'status:InProgress'
```

## Regenerating this reference

This reference is generated from the CLI's own cobra command definitions, so it
stays in step with the binary. To refresh it, build a small doc-gen harness that
assembles the root command from the exported constructors in `internal/cli/root.go`
and runs `cobra/doc` `GenMarkdownTree`, then fold the output into the pages under
`documentation/reference/cli/`.