CLI Commands

Agloom provides a command-line interface built on React + Ink for transpiling canonical configurations into agent-specific files.

Global Options

--help

agloom --help

Displays the general help message with a list of available commands and global options. Calling agloom without any command also displays this help.

Exit code: 0.

--version

agloom --version

Displays the version of the installed Agloom package (read from package.json).

Also available as agloom version.

Exit code: 0.

Unknown Command

If an unknown command is provided, Agloom displays:

Unknown command: <cmd>. Run 'agloom --help' to see available commands.

Exit code: 1.

The --help flag does not suppress this error. Unknown command detection takes priority over global --help.

Commands

transpile

Runs the transpilation pipeline for all registered transpiler modules.

agloom transpile [--adapter <adapterId> | --all] [--clean] [--verbose] [--refresh]

Options

Option	Type	Default	Description
`--adapter <adapterId>`	string	-	Adapter ID from the registry. Mutually exclusive with `--all`.
`--all`	boolean	`false`	Transpile for all adapters in the registry. Mutually exclusive with `--adapter`.
`--clean`	boolean	`false`	Run clean before transpiling (see clean).
`--verbose`	boolean	`false`	Show all steps including those with 0 files.
`--refresh`	boolean	`false`	Force re-fetch of cached git plugins.

When neither --adapter nor --all is specified, adapters are read from .agloom/config.yml.

Adapter Resolution

--adapter <id>: resolves the specified adapter and its dependencies (topological order).
--all: uses all adapters from the registry in definition order.
Neither: loads adapters from config.yml, resolves dependencies, deduplicates.

Dependencies are resolved automatically. For example, --adapter opencode also transpiles the agentsmd adapter first (since opencode.dependsOn = ["agentsmd"]).

Pipeline

For each resolved adapter entry, the command executes transpiler steps in order:

Instructions
Skills
Agents
Docs
Schemas
Overlay step (MCP + Permissions)

Verbose Filtering

Without --verbose, steps with 0 written files and no errors are hidden. If all steps for all adapters are hidden and there are no errors, the output is:

Nothing to transpile.

--clean Behavior

When --clean is provided, the clean procedure runs before transpilation for each adapter entry. With --adapter, the clean result is displayed before transpilation output. With --all or config mode, clean results are not displayed.

Examples

# Transpile using config
agloom transpile

# Transpile for a specific adapter
agloom transpile --adapter claude

# Transpile for all adapters with verbose output
agloom transpile --all --verbose

# Clean then transpile
agloom transpile --clean

Exit Codes

Code	Condition
`0`	All steps completed without errors.
`1`	Any step had errors, both `--adapter` and `--all` specified, config not found (without `--adapter`/`--all`), config error, unknown/hidden adapter.

clean

Removes generated agent-specific files.

agloom clean [--adapter <adapterId> | --all] [--verbose]

Options

Option	Type	Default	Description
`--adapter <adapterId>`	string	-	Adapter ID from the registry. Mutually exclusive with `--all`.
`--all`	boolean	`false`	Clean for all adapters. Mutually exclusive with `--adapter`.
`--verbose`	boolean	`false`	Show details even when 0 files removed.

Behavior

For each resolved adapter, the clean procedure:

Recursively removes directories listed in entry.paths (skills, agents, docs, schemas).
Deletes files listed in entry.targetFiles.

Missing files and directories are silently skipped.

Output

Without --verbose, adapters with 0 removed files and no errors are hidden. If all adapters have 0 removed files:

Nothing to clean.

Examples

agloom clean --adapter claude
agloom clean --all
agloom clean --verbose

Exit Codes

Code	Condition
`0`	All clean operations completed without errors.
`1`	Both `--adapter` and `--all` specified, config not found, config error, unknown/hidden adapter, or deletion error.

init

Imports existing agent-specific files into .agloom/overlays/ and creates the configuration file.

agloom init [--adapter <adapterId> | --all] [--force] [--verbose]

Options

Option	Type	Default	Description
`--adapter <adapterId>`	string	-	Adapter identifier. Mutually exclusive with `--all`.
`--all`	boolean	`false`	Initialize all supported adapters. Mutually exclusive with `--adapter`.
`--force`	boolean	`false`	Overwrite existing files.
`--verbose`	boolean	`false`	Show all steps including 0-file ones.

Behavior

Resolves adapters (same rules as transpile).
Checks if .agloom/ directory exists (error without --force).
Creates .agloom/config.yml when --adapter or --all is specified.
For each adapter, copies files from entry.overlayImportPaths into .agloom/overlays/<adapterId>/.

The generated config.yml includes onboarding comments:

# Agloom configuration
# List of adapters to use by default when no --adapter or --all flag is provided.
# Run 'agloom adapters --all' to see all available adapters.
adapters:
  - claude

Examples

agloom init --adapter claude
agloom init --all
agloom init --adapter opencode --force

Exit Codes

Code	Condition
`0`	All steps completed without errors (including 0 files).
`1`	Both `--adapter` and `--all` specified, config not found (without flags), `.agloom/` already exists without `--force`, overlay directory exists without `--force`, copy or directory creation error.

adapters

Lists available or active adapters.

agloom adapters [--all]

Options

Option	Type	Default	Description
`--all`	boolean	`false`	Show all available (non-hidden) adapters instead of active ones from config.

Behavior

Without --all: loads config and shows active adapters. If no config exists, falls back to showing all non-hidden adapters.
With --all: shows all non-hidden adapters from the registry.

Hidden adapters (e.g., agentsmd) are never displayed.

Output

Active adapters:

  claude       Claude Code
  opencode     OpenCode

Exit code: 0.

format

Formats and lints project files (Markdown, JSON, YAML, TOML).

agloom format [--check] [--all] [<file|glob>...]

Options

Option	Type	Default	Description
`--check`	boolean	`false`	Check files without modifying. Exit code 1 if unformatted.
`--all`	boolean	`false`	Format all supported files in the project (`*/.{md,mdx,json,yaml,yml,toml}`). Mutually exclusive with `<file\|glob>...`.
`<file\|glob>...`	string[]	-	Custom glob patterns or file paths. Mutually exclusive with `--all`.

Default Target Files

When neither --all nor file arguments are provided:

.agloom/**/*.{md,mdx,json,yaml,yml,toml}
**/AGLOOM.md

Supported Formats

Extension	prettier	markdownlint
`.md`, `.mdx`	Yes	Yes
`.json`	Yes	No
`.yaml`, `.yml`	Yes	No
`.toml`	Yes	No

Unsupported extensions are silently skipped.

Configuration Priority

Built-in defaults (bundled in @agloom/markdown-tools).
Native config files (.prettierrc.*, .markdownlint.* in project root).
prettier and markdownlint sections in .agloom/config.yml (shallow merge on top).

Excluded Directories

Glob expansion always excludes: node_modules, .git, dist, build, coverage, .next, .turbo, .cache, and paths matching .gitignore.

Examples

# Format default files
agloom format

# Check without modifying
agloom format --check

# Format all supported files
agloom format --all

# Format specific files
agloom format "src/**/*.md" ".agloom/**/*.yaml"

Exit Codes

Code	Condition
`0`	Format completed without errors, or all files pass check.
`1`	Format errors, files need formatting (check mode), config parse error, or `--all` used with file arguments.

help

Shows help topics or displays a specific help topic rendered from Markdown.

agloom help [<topic>]

Arguments

Argument	Type	Description
`<topic>`	string	Topic name. Full format: `guide/getting-started`, `reference/cli`. Short format (slug only): `cli`, `plugins`.

Behavior

Without <topic>: displays a categorized list of all available help topics (Guide and Reference).

With <topic>: resolves the topic name, reads the corresponding Markdown file from docs/guide/ or docs/reference/, strips frontmatter, and renders to the terminal using marked + marked-terminal.

Short topic names (without category prefix) are searched across all categories. If the slug is ambiguous (exists in multiple categories), an error lists matching topics.

Exit Codes

Code	Condition
`0`	Topic list displayed or topic rendered successfully.
`1`	Topic not found, ambiguous topic, read error, no topics available.

cache clean

Clears the plugin cache directory.

agloom cache clean

Git plugins are cached in ~/.agloom/cache/plugins/. This command removes all cached plugins, forcing re-fetch on the next transpile.

Exit code: 0.

Global Options​

--help​

--version​

Unknown Command​

Commands​

transpile​

Options​

Adapter Resolution​

Pipeline​

Verbose Filtering​

--clean Behavior​

Examples​

Exit Codes​

clean​

Options​

Behavior​

Output​

Examples​

Exit Codes​

init​

Options​

Behavior​

Examples​

Exit Codes​

adapters​

Options​

Behavior​

Output​

format​

Options​

Default Target Files​

Supported Formats​

Configuration Priority​

Excluded Directories​

Examples​

Exit Codes​

help​

Arguments​

Behavior​

Exit Codes​

cache clean​

Global Options

--help

--version

Unknown Command

Commands

transpile

Options

Adapter Resolution

Pipeline

Verbose Filtering

--clean Behavior

Examples

Exit Codes

clean

Options

Behavior

Output

Examples

Exit Codes

init

Options

Behavior

Examples

Exit Codes

adapters

Options

Behavior

Output

format

Options

Default Target Files

Supported Formats

Configuration Priority

Excluded Directories

Examples

Exit Codes

help

Arguments

Behavior

Exit Codes

cache clean