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

Run a service locally with its environment loaded, on every platform.

## Synopsis

```bash
alis run [<pkg>|<path>] [-- <args>...] [flags]
```

Also available as `alis service run`.

## Description

`alis run` loads the product's active environment (`<product>/.alis/.env`, written by the TUI's environment options or by `alis environment refresh --output`) into the process environment, then starts the service:

1. the Makefile `run` target, when the folder has one and `make` is installed (on Windows a POSIX `sh` must be installed too);
2. otherwise the Go main package in the folder (`go run .`);
3. otherwise the first component it detects: a Go server in a subfolder, else a frontend app (`npm run dev` or `pnpm dev`).

Without an argument it runs the current directory; pass a service folder path or a package id. Arguments after `--` go to the program (with make they arrive as `ARGS="…"`).

The service runs in the foreground with its output on this terminal. Ctrl-C stops it and `alis` exits with the service's status (130 when interrupted). There is no JSON for the run itself; `--dry-run --json` prints the plan, never the environment values.

On Windows this is the run contract: GNU make and bash are not part of Windows, so do not call make yourself.

On a workstation the run registers itself with the machine before the service starts: the port it serves (`--port`, else the one the service's `.claude/launch.json`, Makefile `APP_URL` or Vite config names) is attached to the agent session the command runs in, so notes left on the port's pages with the Alis toolbar arrive there, and `--share` lets the people named open the port's address, signed in as themselves, and leave notes of their own. A line on stderr says where the port answers and where its notes go. See [Annotate your app and let agents test it](https://docs.alisx.com/how-to/alis-build/watch-and-help-your-agents-browser.md).

## Flags

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool | false | Show what would run (with `--json`: the plan as JSON) without starting it. |
| `--no-env` | bool | false | Run without loading `<product>/.alis/.env`. |
| `--port <n>` | int | | The port the service listens on; on a workstation it is attached to this agent session before the service starts. |
| `--share <email>` | string | | Let this person open the port's address and leave notes for this session. Repeatable, or comma-separated. Workstation only. |

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

## Examples

```bash title="Terminal"
alis run
alis run acme.shop.orders.v1
alis run --dry-run --json
alis run -- --port 9090
alis run --port 5173 --share reviewer@example.com
```

## Errors

| Code | Meaning |
|---|---|
| `ENV_NOT_FOUND` | The product has no `.alis/.env`. Write one with `alis environment refresh <org>.<product>.<env> --output <product>/.alis/.env`, or use the TUI's environment options. |
| `NOT_A_WORKSTATION` | `--share` was passed off a workstation; a port is shared from there. |