---
title: "alis define"
url: "https://docs.alisx.com/reference/cli/define/"
---
# alis define

Compile a service's `.proto` files in its product's definitions repo into a new definition version, and generate language packages.

## Synopsis

```bash
alis define [<package-id>] [flags]
```

## Description

By default the command waits for the operation to finish, streaming progress to stderr and printing the result to stdout. The service is addressed by package ID, for example `acme.shop.orders.v1`, which maps to the service folder `orders/v1` in the definitions repo. The package ID may be omitted inside the service's directory.

The define uses the latest pushed commit of the definitions repo; pass `--commit` to pin an earlier, reviewed commit. `--install` runs `alis packages install` for the service once the define succeeds, so generated Go, Node, Python, Dart, .NET, Swift and Rust packages are immediately usable.

`--dry-run` validates the service's local `.proto` files, uncommitted edits included, with the same protoc and dependency resolution as a define. Problems are reported with file, line and column. Nothing is defined. It also catches a `package` statement that does not match the service folder, which a define silently skips. It exits non-zero when there are errors.

## Flags

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--async` | bool | false | Start the operation and print its name without waiting. |
| `--commit <sha>` | string | latest commit | Definitions-repo commit to define. |
| `--dry-run` | bool | false | Validate the local `.proto` files (including uncommitted edits) without defining. |
| `--install` | bool | false | After a successful define, install the defined version into the service's packages. |
| `--install-language <lang>` | string | | With `--install`, limit to one language: `go`, `node`, `python`, `dart`, `dotnet`, `swift` or `rust`. |
| `--poll-interval <duration>` | duration | `2s` | How often to poll the operation. |
| `--timeout <duration>` | duration | `0` | Give up waiting after this duration (0 = wait indefinitely; the operation keeps running). |

Plus the [global flags](https://docs.alisx.com/reference/cli/index.md#global-flags).

## Examples

```bash title="Terminal"
alis define acme.shop.orders.v1 --dry-run --json
alis define acme.shop.orders.v1 --json --install
alis define --json --install --install-language go
alis define acme.shop.orders.v1 --json --async
```

## JSON output

The final operation on stdout, following the [output contract](https://docs.alisx.com/reference/cli/output-contract.md). Define-specific failure detail appears under `errorDetails` (the first 40 lines).

`--dry-run --json` returns `valid`, `diagnostics[]` (severity, file, path, line, column, message) and `git` (uncommitted files, unpushed commits, the commit a define would use). Offline, only local checks run and the error envelope carries them under `error.details` with `compiled: false`.

## Notes

- Do not inspect protos through runtime reflection in service code; if generated types look stale, re-run define and `alis packages install`.
- `define` is a mutating-class command under the automation tiers. See [Exit codes](https://docs.alisx.com/reference/cli/exit-codes.md).