Introduction

agiler is the official command-line interface for Agiler. It wraps the same public API that powers the dashboard, so anything you can do in the browser you can script from a shell — list projects, tail logs, upload files, run SQL, restore backups, manage domains and environment variables, and check billing.

The CLI is open source under the MIT license. Source and issues live at github.com/agilercloud/cli.

If you need to call the API directly instead — for example to integrate it into your own application — see the API reference for the full set of endpoints.

Installation

Homebrew (macOS and Linux):

brew install agilercloud/tap/agiler

Install script (macOS and Linux):

curl -fsSL https://raw.githubusercontent.com/agilercloud/cli/main/install.sh | sh

Installs the latest release to ~/.local/bin/agiler. Override with AGILER_VERSION=v0.1.2 or AGILER_INSTALL_DIR=/usr/local/bin (prefix the env vars before the pipeline, e.g. curl ... | AGILER_VERSION=v0.1.2 sh). The script verifies the SHA-256 checksum of the downloaded archive before installing.

From source (requires Go 1.22+):

go install github.com/agilercloud/cli/cmd/agiler@latest

Binary downloads: prebuilt archives for Linux, macOS, and Windows are attached to each GitHub release.

After installing, verify the binary is on your PATH:

agiler version

Quickstart

The first thing to do after installing is log in. agiler login is the safe way to store an API key — on a terminal it reads with echo disabled so the key never lands in shell history; on a pipe it reads one line from stdin.

agiler login
# or, for CI:
printf '%s' "$AGILER_API_KEY" | agiler login

Generate an API key in the dashboard under Settings → API Keys. Scopes are fixed at issue time and enforced server-side, so create a token with the narrowest set of scopes the automation needs.

Once logged in, confirm the API can see you, list your projects, and pick the one you’ll work with most:

agiler whoami
agiler projects list
agiler config set project-id <project-uuid>

That last step writes the project UUID into ~/.config/agiler/config.toml so every project-scoped command (logs, sql, files, backups, variables, domains, rules, usage) targets it by default. You no longer have to repeat the project ID:

agiler logs --follow
agiler files list /wp-content/uploads
agiler backups list

To target a different project for a single command, pass --project <uuid> or -p <uuid> — it overrides the default for that invocation only.

Configuration

The CLI resolves its configuration from the first file it finds, in this order:

1. --config <path> flag
2. ./agiler.toml (current directory)
3. ~/.config/agiler/config.toml (or $AGILER_CONFIG_DIR/config.toml)
4. /etc/agiler/config.toml (system-wide)

The file is TOML:

api_key      = "ak_..."
api_base     = "https://api.agiler.io"   # optional; defaults to production
workspace_id = "..."                     # optional; default workspace
project_id   = "..."                     # optional; default project for project-scoped commands

Environment variables and command-line flags layer on top of the config file. The full precedence is flag → environment variable → config file → built-in default:

To inspect what the CLI actually resolves at runtime — and which source each value came from — run:

agiler config show

Other handy config subcommands:

agiler config get project-id
agiler config set api-base https://api.staging.agiler.io
agiler config unset workspace-id
agiler config set api-key -        # read the value from stdin (bypasses login flow)
agiler config path                 # print the resolved config file path

Set AGILER_NO_UPDATE_CHECK=1 to suppress the once-per-day background “newer version available” notification.

Commands

Run agiler <command> --help for the full flag list of any subcommand. The top-level surface is organized into five groups.

Project operations. Target the project resolved from --project, AGILER_PROJECT_ID, or project_id in config. Setting project-id once means you don’t repeat it on every command.

Resources. CRUD on the things projects live inside.

Reference. Read-only catalogs.

Account.

Maintenance.

Output formats

Every command prints human-readable text by default. Pass --format to switch to a structured format suitable for piping into jq, spreadsheets, or another shell pipeline:

agiler projects list --format json | jq '.[] | select(.runtime == "php-8.3") | .id'
agiler backups list --format csv > backups.csv
agiler logs --format tsv --since 1h | column -t -s $'\t'

The supported values are text (default), json, yaml, csv, and tsv. Structured formats are always plaintext — no color, no progress bars, no human-only adornments — so they’re safe to feed into other tools.

Text output uses subtle ANSI color when stdout (or stderr, for error messages) is a terminal: red error prefixes, bold table headers, dim detail-view labels, and green/yellow status badges. Color is auto-disabled when:

• output is piped or redirected,
• the NO_COLOR environment variable is set,
• --no-color is passed, or
• --quiet is used.

--quiet / -q strips output down to bare IDs — useful for scripting:

for id in $(agiler projects list --quiet); do
  agiler backups create --project "$id"
done

For long downloads, pass --progress to backups download, files get, or billing statement to get a streaming progress indicator on stderr. It’s auto-suppressed when stderr is piped or when writing the payload itself to stdout, so it’s safe to leave on in interactive sessions.

Shell completion

Generate a completion script for your shell and source it from the right place:

# bash (Linux):
agiler completion bash | sudo tee /etc/bash_completion.d/agiler

# bash (macOS, with Homebrew bash-completion):
agiler completion bash > "$(brew --prefix)/etc/bash_completion.d/agiler"

# zsh:
agiler completion zsh > "${fpath[1]}/_agiler"

# fish:
agiler completion fish > ~/.config/fish/completions/agiler.fish

# powershell:
agiler completion powershell | Out-String | Invoke-Expression

Once installed, the shell completes subcommands, flags, and — by calling the live API — project, workspace, region, and runtime IDs. Completion is also wired for the --project, --workspace, --region, and --runtime flag values, so you can tab-complete a project UUID instead of pasting it.

Upgrading

agiler upgrade              # install the latest release
agiler upgrade --check      # report current vs. latest, no changes
agiler upgrade --version v0.1.2   # install a specific tag (supports downgrade)
agiler upgrade --force      # override refusals (dev build, non-canonical path, same version)

agiler upgrade only self-updates installs it can safely manage — the install.sh and manual-download paths. For Homebrew or go install installs, it prints the correct native upgrade command instead. The command queries the GitHub Releases API directly and verifies the SHA-256 of the downloaded archive before replacing the binary.

If you hit the unauthenticated GitHub rate limit (60 requests per hour per IP), set GITHUB_TOKEN to any valid token to raise it.

Debugging

--debug logs each outgoing HTTP request and response to stderr, with the Authorization header redacted. Useful when an unexpected 4xx or 5xx comes back and you want to see the exact request the CLI made:

agiler --debug projects list 2>&1 1>/dev/null   # debug output only
agiler --debug projects list 2>debug.log        # capture to a file

For broader transport-level issues — name resolution, TLS, proxies — Go’s standard HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables are honored by the underlying HTTP client.

Source code and feedback

The CLI is open source. Browse the code, file issues, and watch for releases at github.com/agilercloud/cli. Pull requests are welcome — see the repository’s CONTRIBUTING.md for the development setup.