# CLI command reference

> Find Alice commands, build and run options, package operations, and global diagnostic controls.

Canonical: https://alice-lang.org/documentation/tools/cli/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Invocation

```sh
alice <command> [arguments]
alice path/to/main.al
alice +nightly run main.al
```

A file argument is shorthand for `alice run file.al`. Running `alice` in a terminal without arguments opens the REPL. From source, use `dotnet run --project src/Alice.Cli -- <command>`.

## Create, check, build, and run

| Command                                         | Purpose                                |
| ----------------------------------------------- | -------------------------------------- |
| `alice new name`                                | Create an executable package           |
| `alice new name --lib`                          | Create a library                       |
| `alice new name --game`                         | Create a MonoGame package              |
| `alice new name --workspace`                    | Create a workspace root                |
| `alice check [dir or file]`                     | Check without running                  |
| `alice build [dir or files]`                    | Build package/workspace or loose files |
| `alice build --release`                         | Release configuration                  |
| `alice build --native`                          | NativeAOT publishing                   |
| `alice run [dir or file.al] [member] [-- args]` | Build and run                          |
| `alice emit file.al`                            | Print lowered C#                       |
| `alice clean [dir]`                             | Remove `bin/` and `obj/`               |

Loose-file builds follow `require` transitively. Build options include `-o output` and `-r reference.dll` where applicable. Project builds use manifest dependencies and MSBuild. For a workspace with several executables, specify a member.

```sh
alice run main.al -- first second
alice build main.al -o out/app.dll -r references/Library.dll
```

Arguments after `--` belong to the application and are available through `ARGV`.

## Tests and formatting

| Command                                    | Purpose                                       |
| ------------------------------------------ | --------------------------------------------- |
| `alice test [files]`                       | Run project or selected tests                 |
| `alice test file.al:LINE`                  | Run one example/group                         |
| `alice test -e text`                       | Filter by full name                           |
| `alice test --format doc\|progress\|junit` | Choose report format                          |
| `alice test --seed N --order random`       | Reproducible shuffle                          |
| `alice test --fail-fast`                   | Stop after a failure                          |
| `alice test --profile`                     | Show slowest examples                         |
| `alice fmt [paths]`                        | Format in place                               |
| `alice fmt --check [paths]`                | Report formatting differences without editing |

Read [testing](https://alice-lang.org/documentation/guides/testing.md) for assertions and matchers.

## Packages

| Command                               | Purpose                                   |
| ------------------------------------- | ----------------------------------------- |
| `alice add package --version version` | Record and restore a NuGet dependency     |
| `alice add package --path directory`  | Add to a selected package directory       |
| `alice remove package [--no-restore]` | Remove a dependency                       |
| `alice list`                          | List dependencies and cache location      |
| `alice search term`                   | Search nuget.org                          |
| `alice install`                       | Restore dependencies and refresh the lock |
| `alice install --tool name`           | Install/update a .NET global tool         |
| `alice update`                        | Refresh resolved dependency versions      |
| `alice cache [--clear]`               | Show or clear the shared NuGet cache      |

Version constraints and path dependencies belong in [alice.toml](https://alice-lang.org/documentation/tools/manifest.md). Clearing the shared cache affects other .NET projects that use it.

## Environment and tools

`alice version` (or `-V`) shows version/runtime details. `alice doctor` checks setup. `alice toolchain ...`, `alice self ...`, and `alice completions ...` manage installed versions and shell integration. `alice lsp --stdio` starts the language server for an editor.

`alice gen` is an internal SDK command. Use `alice.toml` and the normal CLI rather than manually driving generated projects. Alice has no `sln` command.

## Global flags and exit codes

| Flag                | Effect                                 |
| ------------------- | -------------------------------------- |
| `--lang en\|pt\|es` | Diagnostic language; also `ALICE_LANG` |
| `-q`, `--quiet`     | Suppress routine progress output       |
| `--no-color`        | Disable terminal color                 |
| `--verbose`         | Include details for internal errors    |

Success exits with 0. Program/test/build failures normally exit with 1, usage mistakes with 2, and internal failures with 70. Preserve the command's exit code in scripts. Diagnostics include a source location and help where available.

## Continue reading

- Previous: [Editor setup](https://alice-lang.org/documentation/tools/editors.md)
- Next: [The alice.toml manifest](https://alice-lang.org/documentation/tools/manifest.md)