CLI Reference
Complete command-line interface documentation for Angreal.
angreal [OPTIONS] <SUBCOMMAND>
-h, --help
- Print help information-v, --verbose
- Verbose level (may be used multiple times for more verbosity)-V, --version
- Print version information
The verbose flag can be repeated for increased verbosity:
angreal -v init template/ # Basic verbose output
angreal -vv init template/ # More detailed output
angreal -vvv init template/ # Maximum verbosity
Initialize a new project from an Angreal template.
angreal init <TEMPLATE> [OPTIONS]
Arguments:
TEMPLATE
- Template source (local path, Git URL, or GitHub shorthand)
Options:
-f, --force
- Force the rendering of a template, even if paths/files already exist-d, --defaults
- Use default values provided in the angreal.toml--values <FILE>
- Provide values to template, bypassing template toml
Template Sources & Examples:
# Local template
angreal init ./my-template
# Git repository
angreal init https://github.com/user/template.git
# GitHub catalog template
angreal init template
# With options
angreal init template/ --force --defaults
angreal init template/ --values values.toml
NoteAvailable Templates: Browse the official Angreal templates at github.com/angreal to find pre-built templates for various project types.
Template Resolution: Angreal resolves templates in the following order:
- Local path if it exists
- Path in
~/.angrealrc/
if it exists - GitHub repository at
https://github.com/angreal/template_name
- Git repository at the specified URL
InfoFor a detailed explanation of how Angreal resolves and processes templates, see Angreal Init Behavior.
Get a structured view of all available commands and tasks in an Angreal project.
angreal tree [OPTIONS]
Options:
--json
- Output command structure in JSON format for machine processing
Examples:
# Human-readable tree view
angreal tree
# JSON output for tooling integration
angreal tree --json
MCP Integration:
The tree
command is designed for integration with Model Context Protocol (MCP) servers and AI agents. It provides a machine-readable JSON schema that includes:
- Project context (root directory, Angreal version)
- Complete command hierarchy with full command paths
- Usage guidance (
when_to_use
andwhen_not_to_use
fields) - Parameter information with types and requirements
This enables AI agents to understand available commands and make informed decisions about when and how to use them. The JSON output is optimized for MCP consumption and automated tooling integration.
Create and manage command aliases for white-labeling Angreal.
angreal alias <SUBCOMMAND>
Subcommands:
create <name>
- Create a new command aliasremove <name>
- Remove an existing aliaslist
- List all registered aliases
Examples:
# Create a custom command name
angreal alias create mycompany-tool
# Now you can use 'mycompany-tool' instead of 'angreal'
mycompany-tool init template/
# List all aliases
angreal alias list
# Remove an alias
angreal alias remove mycompany-tool
Install and manage shell completion for Angreal.
angreal completion <SUBCOMMAND>
Subcommands:
install [shell]
- Install shell completion (bash, zsh)uninstall [shell]
- Uninstall shell completionstatus
- Show completion installation status
Examples:
# Install completion for current shell
angreal completion install
# Install for specific shell
angreal completion install bash
# Check completion status
angreal completion status
# Uninstall completion
angreal completion uninstall
Print help information for Angreal or a specific subcommand.
angreal help [SUBCOMMAND]
Examples:
# General help
angreal help
# Help for a specific command
angreal help init
# Alternative syntax
angreal init --help
When you’re inside an Angreal project (a directory containing .angreal/
), the CLI behavior changes significantly.
WarningImportant: When inside an Angreal project, you lose access to theinit
command and instead get the project’s custom tasks. To useinit
, you must run it from outside any Angreal project directory.
Angreal automatically discovers tasks by:
- Looking for
.angreal/
directory in current or parent directories - Loading Python files matching the pattern
task_*.py
- Registering functions decorated with
@angreal.command
- Replacing the default commands with project-specific ones
Angreal’s available commands are determined by the nearest .angreal/
directory found when walking up the directory tree from your current location.
Outside any Angreal project:
angreal --help
# SUBCOMMANDS:
# help Print this message or the help of the given subcommand(s)
# init Initialize an Angreal template from source.
Inside an Angreal project:
cd my-angreal-project/
angreal --help
# SUBCOMMANDS:
# help Print this message or the help of the given subcommand(s)
# build Build the project
# test Run tests
# deploy Deploy to production
#
# Note: 'init' is no longer available!
# Run a project task
angreal build
# Get help for a project task
angreal build --help
# Run with arguments
angreal deploy --environment staging --dry-run
# Error: Template not found
angreal init nonexistent/template
# Solutions:
# 1. Check the template URL/path
# 2. Ensure you have internet access for remote templates
# 3. Check if the repository is public
# 4. Try with full Git URL
# Error: Task 'build' not found
angreal build
# Solutions:
# 1. Check if you're in an Angreal project:
ls .angreal/
# 2. List available tasks:
angreal --help
# 3. Check task file naming:
ls .angreal/task_*.py
# Error: angreal command not found
# Linux/macOS:
which angreal
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Windows:
where angreal
# Add to PATH: %APPDATA%\Python\Scripts
- Quick Start - Getting started with Angreal
- Python API Reference - Task definition API
- Configuration Reference - Configuration file formats
- How-to Guides - Common task examples