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.
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