> For the complete documentation index, see [llms.txt](https://docs.aviator.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aviator.co/verify/how-to-guides/managing-invariants-with-the-cli.md).

# Managing invariants with the CLI

You can review and manage your account's [invariants](/verify/concepts/invariants.md) from the terminal with the [`aviator` CLI](/verify/reference/cli.md). This guide covers what makes an invariant worth keeping, then the commands.

### What makes a good invariant

An invariant is a rule an LLM checks against what a pull request changed. Good ones need judgment about what the change does, like "New HTTP endpoints must enforce authentication before business logic."

* **One rule per invariant.**
* **Put scope in** [**conditions**](/verify/reference/invariant-conditions.md), not the body. An invariant is only considered for pull requests that change a file matching its conditions.
* **Carve out recurring exceptions,** [**waive**](/verify/concepts/invariants.md#waivers) **rare ones.** Only name an exception in the body if it keeps coming up.

Verify picks which in-scope invariants apply by comparing each one's title, category, reason, and body to the change's spec and plan, so make the rule's subject clear in its title and body.

### Working with the CLI

Listing works with any API token. Creating or changing an invariant needs a user signed in with `aviator login` or a personal access token. Anyone can create one; editing, approving, rejecting, and deleting need a maintainer, an admin, or a member of the invariant's [owner team](/verify/concepts/invariants.md#owner-teams).

| Command                                          | What it does                                                                              |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `aviator invariants list`                        | List invariants, newest first. Filter with `--status`, `--repo`, `--source`, and `--ids`. |
| `aviator invariants categories`                  | List the category slugs that `create` and `edit` accept.                                  |
| `aviator invariants create`                      | Create an invariant. Needs `--title`, `--category`, and `--body` or `--body-file`.        |
| `aviator invariants edit <id>`                   | Change only the fields you pass.                                                          |
| `aviator invariants approve <id>...`             | Activate invariants so Verify starts applying them.                                       |
| `aviator invariants reject <id>...`              | Stop applying invariants but keep them on record.                                         |
| `aviator invariants set-status <status> <id>...` | Set any status, for example to restore a rejected invariant to `pending`.                 |
| `aviator invariants delete <id>`                 | Delete an invariant permanently.                                                          |

An invariant's status is `pending` (proposed, not applied), `active` (applied), or `rejected` (not applied, kept on record). An active invariant can also be turned off with `edit --disable`, which `list` shows as `active (disabled)`.

An invariant applies to every repository unless you pass `--repo owner/repo`, once per repository. Add conditions with `--condition`, once each:

| Flag                                         | Settings page group |
| -------------------------------------------- | ------------------- |
| `--condition 'file_path_glob=src/**/*.go'`   | Include files       |
| `--condition 'file_path_glob!=**/*_test.go'` | Exclude files       |
| `--condition 'language=go'`                  | Language            |

```bash
aviator invariants create \
  --title "HTTP handlers authenticate before business logic" \
  --category security \
  --body-file handler-auth.md \
  --condition 'file_path_glob=src/**/*.go' \
  --condition 'file_path_glob!=**/*_test.go'
```

Things to know:

* `create` activates the invariant immediately. Pass `--disable` to create it turned off.
* On `edit`, `--condition` and `--repo` replace the existing set, so pass all the ones you want to keep.
* `--enable` and `--disable` only apply to active invariants. Use `approve` for a pending one.
* `reason` explains why Aviator proposed the invariant. Verify reads it when picking invariants, and it can't be edited.
* Use `--body-file` to avoid shell quoting problems.
* `list` doesn't show bodies. Add `--json` to any command for the full response.
* `list` returns 20 invariants per page by default, up to 100 with `--limit`. Page with `--page` until `has_more` is false.

### See also

* [Invariant conditions](/verify/reference/invariant-conditions.md): exact glob and language matching rules
* [Concepts: Invariants](/verify/concepts/invariants.md): sources, categories, and waivers
* [Aviator CLI](/verify/reference/cli.md): install and authentication


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.aviator.co/verify/how-to-guides/managing-invariants-with-the-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.