Quick Start
Get started with Earl in minutes
The fastest way to get started is to prompt your AI agent:
Fetch https://raw.githubusercontent.com/brwse/earl/main/skills/getting-started-with-earl/SKILL.md
and any files it references under
https://raw.githubusercontent.com/brwse/earl/main/skills/getting-started-with-earl/references/
then follow the skill to help me get started with Earl.Your agent will install Earl, walk you through setup, and build your first template — all from a single prompt.
To do it manually instead, follow the steps below.
Install
Earl is a single binary with no runtime dependencies.
curl -fsSL https://raw.githubusercontent.com/brwse/earl/main/scripts/install.sh | bashOptions:
| Flag | Description |
|---|---|
--version <version> | Install a specific version (e.g., 0.2.0 or v0.2.0). Default: latest |
--install-dir <path> | Prefix directory. Binary goes into <path>/bin |
--bin-dir <path> | Install the binary directly into this directory |
Default install location: ~/.local/bin (or /usr/local/bin when run as root). Ensure the install directory is on your PATH.
irm https://raw.githubusercontent.com/brwse/earl/main/scripts/install.ps1 | iexParameters: -Version, -InstallDir, -BinDir.
Default install location: %LOCALAPPDATA%\Programs\earl\bin.
Requires a Rust toolchain and Node.js + pnpm (earl embeds web playground assets at compile time).
cargo install earlInstalls from crates.io.
All protocols are enabled by default. To install with only the protocols you need:
cargo install earl --no-default-features --features http,graphql| Flag | Description | Default |
|---|---|---|
http | HTTP protocol support | Yes |
graphql | GraphQL protocol (requires http) | Yes |
grpc | gRPC protocol support | Yes |
bash | Sandboxed Bash script execution | Yes |
sql | SQL query execution with sandboxing | Yes |
The graphql feature automatically enables http since GraphQL requests are
sent over HTTP.
Verify the installation:
earl --versionYour First Call
Import the example template
earl templates import https://raw.githubusercontent.com/brwse/earl/main/examples/bash/system.hclEarl copies the template into your local ./templates/ directory. Since system.hcl declares no secrets, there is nothing else to configure.
List available commands
earl templates listYou should see system.disk_usage and system.list_files in the output.
Make a call
earl call system.list_files --path /tmpEarl executes ls -la /tmp inside a sandboxed Bash environment and prints the result.
Adding Secrets (GitHub Example)
Import the GitHub template
earl templates import https://raw.githubusercontent.com/brwse/earl/main/templates/github.hclEarl prints the required secrets for this template. The GitHub template uses github.token for authentication.
Store your token
earl secrets set github.tokenYou will be prompted to enter the value. The token is stored in your OS keychain and never appears in CLI output.
To pipe from an environment variable instead:
printf '%s' "$GITHUB_TOKEN" | earl secrets set github.token --stdinValidate setup
earl doctorDoctor checks that your config file is loadable, templates parse correctly, and required secrets are present.
Search repositories
earl call github.search_repos --q "language:rust stars:>1000"Earl resolves the github.token secret from your keychain, builds the HTTP request from the template, and returns the result.
What's Next
- Browse commands — Run
earl templates search "what you want to do"for semantic search across all loaded templates. - Web playground — Run
earl webto launch a local web UI for browsing and testing commands. - MCP integration — Run
earl mcpto expose your templates as MCP tools for AI agents. See MCP Integration. - Lock it down — Restrict write access to
~/.config/earl/config.tomland your template files. See Security. - Write your own templates — See Templates for the HCL template format.
Shell Completions
Generate completion scripts for your shell:
earl completion bash > ~/.local/share/bash-completion/completions/earlearl completion zsh > ~/.zfunc/_earlearl completion fish > ~/.config/fish/completions/earl.fishearl completion powershell >> $PROFILEElvish is also supported via earl completion elvish.