am CLI
am is the official command-line tool for managing Amplitude projects: scaffolding a new one, authoring its JSON assets, and building them into the binaries the engine loads at runtime. It's a separate tool from the SDK's own amac, amir, and ampk, which operate on individual files rather than a whole project.
Info
The source is at github.com/AmplitudeAudio/cli.
Installation¶
Pre-built binaries (am, or am.exe on Windows) are published on every release at github.com/AmplitudeAudio/cli/releases, for Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), and Windows (x86_64).
To build from source, you need Rust 1.85+ and a clone of the SDK (required at build time for FlatBuffers schema code generation):
git clone https://github.com/AmplitudeAudio/cli.git
git clone https://github.com/AmplitudeAudio/sdk.git
export AM_SDK_PATH="$(pwd)/sdk"
cd cli
cargo build --release
Global Options¶
These flags work with every command:
| Flag | Description |
|---|---|
-v, --verbose | Enable debug and trace logging. |
-q, --quiet | Suppress informational output (errors are always shown). |
--json | Output machine-readable JSON instead of formatted text. |
--non-interactive | Disable interactive prompts; fail instead of asking for missing input. |
-h, --help | Show help for the current command. |
-V, --version | Show the am version. |
am project¶
Manages the project itself: creation, registration, validation, and building.
| Command | Description |
|---|---|
am project init [name] [--template <name>] [--no-register] | Creates a new project from a template, and registers it unless --no-register is given. |
am project register [path] | Registers an existing project directory so other commands (and am project list) can find it by name. |
am project unregister <name> [--delete-files] | Unregisters a project, optionally deleting its files. |
am project list [--favorite \| --no-favorite] [--json] | Lists registered projects. |
am project favorite <name> [--set \| --unset] | Marks or unmarks a project as a favorite. |
am project info [name] | Shows details of a project (the current directory's project if name is omitted). |
am project validate [--sounds-only \| --collections-only \| ...] [--json] | Validates every asset in the project, or only one asset type. |
am project build [--output <dir>] [--clean] [--fail-fast] | Validates, then compiles every asset into the binaries the engine loads. |
am project init my_game --template o3de
am project validate --json
am project build --output dist/ --clean
Build requires the SDK
am project build needs the Amplitude SDK's FlatBuffers schemas to compile assets, so it requires AM_SDK_PATH (or an SDK discoverable on your system) the same way building am from source does. No separate flatc install is needed — see Compiling Amplitude Projects for the full walkthrough.
am asset¶
Authors the JSON asset files a project is made of. Seven asset types are supported, each with create, list, and update subcommands (and delete, except for sound):
| Type | Maps to | Notes |
|---|---|---|
sound | Sound | No delete subcommand yet. |
collection | Collection | |
effect | Effect | |
switch | Switch | |
switch-container | Switch Container | Note the hyphen: am asset switch-container. |
event | Event | |
soundbank | Sound bank |
sound has the most options, and illustrates the general shape:
am asset sound create explosion --file audio/explosion.wav
am asset sound create footstep --file audio/step.wav --gain 0.8 --loop
am asset sound create ambient --stream --spatialization position
am asset sound update explosion --gain 0.5
am asset sound list --json
Any flag omitted from a create or update call that still needs a value triggers an interactive prompt, unless --non-interactive is set — in which case the command fails instead of asking.
A few types have their own shape worth knowing about:
# switch-container: map switch states to sounds
am asset switch-container create footsteps --switch surface_type --map wood=wood_step --map stone=stone_step
# soundbank: include other assets by "type:name[,name,...]"
am asset soundbank create main_bank --include sound:explosion,footstep
am asset soundbank update main_bank --add sound:newsfx --remove sound:oldsfx
# event: actions as "type:target_id[,target_id,...]"
am asset event create play_music --action play:12345
Run am asset <type> create --help (or update/list/delete) for the full, current flag list of any one subcommand.
am template¶
Manages the project templates am project init can scaffold from.
am template list
am template info default
am template register /path/to/template --name my_template
am template unregister my_template
am sdk¶
Checks whether an Amplitude SDK installation can be discovered (via AM_SDK_PATH or a well-known location), and reports its path.
am sudo¶
Administrative operations, destructive by nature and not part of everyday project work:
Resets am's own local database (registered projects, templates, favorites) — not anything inside a project. --yes skips the confirmation prompt.
am completions¶
am completions bash > ~/.local/share/bash-completion/completions/am
am completions zsh > ~/.zfunc/_am
am completions fish > ~/.config/fish/completions/am.fish
Generates a shell completion script for bash, zsh, or fish. Completions cover commands, subcommands, and flags — not asset or project names, which still need to be typed out.