alis run

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

Synopsis

❯ 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.

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.

Examples

Shell

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.