# Definitions

A **definition** is a named subset of platforms and actions — the catalog an installed `omni-cli` carries. It is the unit of selection, install, enforcement, sharing, and live update: the CLI registers only the commands in its definition, and the signed bundle it refreshes at runtime contains nothing else.

## Why curate at all

The definition is built for the agent, not for the human. Two payoffs:

- **Smaller context.** `omni-cli discovery` lists only what the definition serves, so the agent loads a catalog sized to the workflow instead of every action on every platform.
- **Smaller blast radius.** An action that wasn't selected doesn't exist in the build — it isn't served, isn't registered, and can't run. Leave unneeded mutating actions out of the definition and no prompt injection or model mistake can reach them.

## Creating and editing

Definitions live in the dashboard at https://omnicli.io/definitions. Create one, give it a lowercase hyphenated name (it becomes part of the install build), and pick platforms and actions from the searchable platform list — search by platform name and expand a platform to choose its actions. The summary rail keeps a running count of platforms, actions, and mutating actions. Actions marked *writes* change remote data; the editor shows which actions the plan includes.

Saving a definition lands on its install page, which mints the install one-liner (Linux/macOS and Windows); each definition on the list page also links to it via **Install** — see [Install & Sign In](https://omnicli.io/docs/install.md). What each plan includes is at https://omnicli.io/pricing.

## Versioning and propagation

Every edit bumps the definition's version. Installed CLIs pick the new version up on their next bundle refresh — refreshes happen silently whenever the CLI can reach the backend, so there is nothing to reinstall (the binary is universal; only the signed bundle changes). To force it immediately on a machine:

```
omni-cli definitions update    # fetch a freshly-signed bundle now
omni-cli definitions status    # active definition, version, deadlines
```

## Sharing to a team

On team plans a definition can be shared to the team: every active member can install and use it, while editing stays with the owner. A team owner can also create a definition as team-owned from the start.

## What happens on plan changes

If the plan changes, definitions it no longer covers are **disabled** — they stop being served (an installed CLI's next refresh is refused) and the dashboard shows them as disabled, where the only available action is deleting them. Nothing is deleted automatically: selections are preserved, and definitions reactivate when the plan covers them again. On the Free plan one definition is active at a time; deleting the active one automatically re-enables your most recently used free-compatible definition.