Config File Reference

amoxide stores its configuration in ~/.config/amoxide/ using TOML files. You rarely need to edit these by hand — the CLI manages them — but understanding the format helps when debugging or sharing setups.

File Overview

File	Purpose
config.toml	Global aliases and shell options
profiles.toml	All profile definitions and their aliases
session.toml	Active profile list (which profiles are currently on)
security.toml	Trust decisions for project .aliases files
.aliases	Project-local aliases (lives in project root)

config.toml — Global Config

# Global aliases — always available
[aliases]
helo = "echo hello world"
ll = "ls -lha"

# Global subcommand aliases — short forms for subcommand-based tools
[subcommands]
"jj:ab" = ["abandon"]
"jj:b:l" = ["branch", "list"]

# Global variables — named placeholders for alias commands
[vars]
editor = "hx"

The [vars] table holds reusable values referenced as inside alias commands. See Variables for resolution rules.

config.toml — Shell Options

Shell-specific rendering options can be set under the [shell.<name>] section.

Fish: [shell.fish]

Key	Type	Default	Description
use_abbr	bool	false	Render simple aliases as fish abbreviations (abbr --add) instead of alias

[shell.fish]
use_abbr = true

When use_abbr = true, every simple alias from every layer (global, profile, and project) is emitted as an abbreviation. Abbreviations expand in-line as you type, which keeps your command history clean.

Parameterized aliases — those that use {{1}} or {{@}} placeholders — are always emitted as function definitions regardless of this setting, because fish abbreviations do not support arguments.

Example output with use_abbr = true:

abbr --add gs "git status"
abbr --add ll "ls -lha"

Example output for a parameterized alias (always a function, regardless of use_abbr):

function cmf
    cm feat: $argv
end

To enable this setting, edit ~/.config/amoxide/config.toml manually and add the [shell.fish] block shown above. Then reinitialise in place to apply the change without restarting your shell:

am init -f fish | source

config.toml — Logging

Controls the verbosity of messages shown when navigating into and out of directories with project aliases.

Key	Type	Default	Description
project_loading	string	"verbose"	Message shown when entering a project with trusted .aliases
project_unloading	string	"verbose"	Message shown when leaving a project

Accepted values for both keys:

Value	Effect
"off"	No message is shown
"short"	One-line summary (loading: am: loaded .aliases: b, t; unloading: am: .aliases unloaded)
"verbose"	Full detail (loading: aligned alias table; unloading: change summary with added/unloaded counts)

[logging]
project_loading = "verbose"
project_unloading = "short"

To suppress all navigation messages:

[logging]
project_loading = "off"
project_unloading = "off"

config.toml — Update Check

Controls the crates.io update check. See Update Check for details.

Key	Type	Default	Description
check	bool	true	Whether listing commands check crates.io for a newer release

[update]
check = false

You can also disable the check per-invocation with the AM_NO_UPDATE_CHECK environment variable.

profiles.toml — Profile Definitions

[[profiles]]
name = "git"

[profiles.aliases]
ga = "git commit --amend"
gcm = "git commit -S --signoff -m"
gst = "git status"

[[profiles]]
name = "rust"

[profiles.aliases]
f = "cargo fmt"
t = "cargo test --all-features"
l = "cargo clippy --locked --all-targets -- -D warnings"
cc = "cargo build {{opt-flags}}"

[profiles.subcommands]
"cargo:t" = ["test", "--all-features"]

[profiles.vars]
opt-flags = "-C opt-level=3"

[[profiles]]
name = "node"

[profiles.aliases]
t = "npm run test"
b = "npm run build"

Each [[profiles]] block defines a named profile with its aliases and optional subcommand aliases. Note that different profiles can use the same alias name (e.g., t in both rust and node) — whichever profile has higher priority in active_profiles wins.

The optional [profiles.vars] table holds variables scoped to that profile, referenced as inside the profile's aliases. See Variables.

session.toml — Active Profiles

Tracks which profiles are currently active and in what order. Managed automatically by am profile use and am use — you rarely need to edit this directly.

active_profiles = ["git", "rust"]

The order determines precedence: the last entry has the highest priority. If both git and rust define an alias with the same name, rust wins.

security.toml — Trust Decisions

Tracks which project .aliases files you have reviewed and trusted. Managed automatically by am trust and am untrust — you shouldn't need to edit this file.

[[trusted]]
path = "/home/user/projects/my-app/.aliases"
hash = "a1b2c3d4e5f6..."

[[untrusted]]
path = "/home/user/projects/declined-repo/.aliases"

Each trusted entry stores the file path and a BLAKE3 hash of its contents. If the file changes, the hash won't match and amoxide will ask you to re-review. See Trust Model for details.

A third section, [[tampered]], appears automatically when a trusted file is modified outside of am. It clears when you run am trust to review the changes.

.aliases — Project Aliases

This file lives in your project root and is loaded automatically when you cd into the directory.

[aliases]
i = "cargo install --path crates/am && cargo install --path crates/am-tui"
l = "cargo clippy --locked --all-targets -- -D warnings"
t = "cargo test --all-features"
b = "cargo build {{target}}"

[subcommands]
"jj:ab" = ["abandon"]
"jj:b:l" = ["branch", "list"]

[vars]
target = "--target x86_64-unknown-linux-musl"

Project aliases override profile aliases with the same name. This lets you customize shortcuts per project without changing your global setup.

The optional [vars] table holds project-scoped variables, referenced as inside the project's aliases. See Variables.

Priority Order

When multiple layers define the same alias name, the most specific one wins:

Project aliases (.aliases)    ← highest priority
  ↑ overrides
Active profiles (last wins)
  ↑ overrides
Global aliases (config.toml)  ← lowest priority

The same priority order applies to subcommand aliases. A [subcommands] entry in .aliases overrides the same key from an active profile, which overrides the same key in config.toml.

See Subcommand Aliases for usage examples and how the shell wrappers are generated.