CLI

The Crow CLI (crow) allows you to interact with Crow CI from the command line. You can manage repositories, pipelines, secrets, and more.

Installation

Binary Download

Download the CLI from the project’s releases page. Choose the appropriate binary for your platform: Linux and macOS builds ship as crow-cli_<os>_<arch>.tar.gz, the Windows build as crow-cli_windows_amd64.zip.

Note

A homebrew tap for simplified installation on macOS is planned.

Container Image

The CLI is also available as a container image:

docker run --pull always \
  -e CROW_TOKEN=$CROW_TOKEN \
  -e CROW_SERVER=$CROW_SERVER \
  --rm -it codefloe.com/crowci/crow-cli:dev info

Note

The container image is named crow-cli to align with server and agent image naming. The executable inside is named crow.

Configuration

The CLI needs a Crow server and a personal access token. Generate a token in the Crow CI web interface under Settings > Personal Access Tokens. A scoped token only reaches what its scopes allow, see Access tokens.

Servers

Add each server once and store a token for it:

crow server add codefloe https://ci.codefloe.com
crow server login codefloe

crow server add asks the server which forges it builds (for example codefloe.com) and stores them as the server’s forge hosts. Inside a git checkout, the CLI then picks the server whose forge hosts match a git remote and the repository from that remote, so per-repository commands need no arguments:

cd ~/src/my-project
crow pipeline ls

A command picks its server in this order:

1. --server or CROW_SERVER: the name of a configured server, or a URL.
2. The server whose forge hosts match a git remote of the working directory (upstream first, then origin, then any other remote).
3. The default server: the first one added, or the one set with crow server set-default.
4. The only configured server.

crow server current shows which server and repository the working directory resolves to, and why.

Command	Description
crow server add <name> <url>	Add a server. --default makes it the default, --forge-host (repeatable) sets the forge hosts instead of detecting them, --token-env VAR or --token-command "cmd args" reads the token from an environment variable or a command instead of storing it
crow server login [name]	Prompt for a token, check it against the server and store it. --token or a token piped to stdin skip the prompt
crow server logout [name]	Forget the stored token
crow server ls	List servers, their forge hosts and where their token comes from (-o json/yaml)
crow server current	Show the server and repository the working directory resolves to
crow server set-default <name>	Make a server the default
crow server refresh [name]	Ask one or all servers for their forge hosts and add new ones; hosts set with --forge-host are kept
crow server rm <name>	Remove a server and its stored token (-f skips the confirmation)

Servers live in $XDG_CONFIG_HOME/crow/instances.yaml (usually ~/.config/crow/instances.yaml; change it with --config or CROW_CONFIG). Stored tokens go to credentials.yaml next to it, readable only by your user, so instances.yaml holds no secrets and can be kept in your dotfiles. A stored token is tied to the server URL it was stored for: if the URL of a server changes, run crow server login again. The file can also be edited by hand, and may be a symlink, e.g. into a dotfiles repository. login and logout leave it untouched; commands that change servers rewrite it, which drops comments:

instances:
  - name: codefloe
    url: https://ci.codefloe.com
    forge_hosts: [codefloe.com]
    default: true
  - name: company
    url: https://ci.example.com
    forge_hosts: [git.example.com]
    # any command that prints the token, e.g. from a password manager
    token_command: ["pass", "show", "crow/company"]

crow mcp reads the same file, see MCP Server for Coding Agents.

Note

Forge hosts are detected from the forge URL configured on the Crow server. If your git remotes use a different host name (for example an internal URL on the server and a public one in your clones), set it with --forge-host.

Environment variables

Without an instances file, or for one-off calls, set the server and token directly:

Variable	Description
CROW_SERVER	URL of your Crow CI server (e.g., https://ci.example.com), or the name of a configured server
CROW_TOKEN	Personal access token

A URL together with a token is always used as given. For a configured server, --token on the command line overrides its stored token. CROW_TOKEN from the environment is never sent to a configured server, because it usually belongs to another one; set CROW_SERVER to a URL to use it.

Common Commands

Repository Management

# List repositories
crow repo ls

# Show repository info
crow repo show owner/repo

# Sync repositories from forge
crow repo sync

Pipeline Management

# List recent pipelines
crow pipeline ls owner/repo

# Show pipeline details
crow pipeline info owner/repo <pipeline-id>

# Trigger a new pipeline
crow pipeline start owner/repo

# Stop a running pipeline
crow pipeline stop owner/repo <pipeline-id>

pipeline workflow

Subcommands for managing workflows within a pipeline run. Currently used for workflow-level approval gates.

# Approve a blocked workflow
crow pipeline workflow approve <repo> <pipeline-number> <workflow-name> [--reason "..."]

# Decline a blocked workflow
crow pipeline workflow decline <repo> <pipeline-number> <workflow-name> [--reason "..."]

The workflow is resolved by name within the given pipeline. The caller must be in the workflow’s approvers list, or hold push permission on the repo if no approvers are configured. An optional --reason is recorded in the audit trail.

Secrets Management

# List secrets
crow secret ls owner/repo

# Add a secret
crow secret add owner/repo --name SECRET_NAME --value "secret-value"

# Remove a secret
crow secret rm owner/repo SECRET_NAME

Local Pipeline Execution

# Run pipeline locally (requires Docker)
crow exec

# Run a single workflow file
crow exec .crow/build.yaml

# Run several workflow files, or every workflow in a directory
crow exec .crow/build.yaml .crow/test.yaml
crow exec .crow/

# Supply secrets inline as key=value pairs
crow exec --secrets 'token=abc,api_key=xyz'

# Supply secrets from a YAML file on disk
crow exec --secrets-file ./secrets.yaml

crow exec takes workflow files or directories as arguments; there is no --workflow flag. Without arguments it uses the default config (.crow/, .crow.yaml, …) in the current directory. For a file inside .crow/ or .woodpecker/, the repository root is mounted as the workspace; pass --repo-path to choose another directory.

--secrets-file reads a YAML map of name: value pairs and is also configurable via CROW_SECRETS_FILE (or WOODPECKER_SECRETS_FILE).

Linting

crow lint validates local pipeline configuration files against the Crow schema — it does not fetch configuration from the server or forge. Point it at a single YAML/Jsonnet file or a directory containing workflow files.

# Lint a directory of workflow files
crow lint .crow/

# Lint a single workflow file
crow lint .crow/build.yaml

# Treat warnings as errors
crow lint --strict .crow/

MCP Server for Coding Agents

crow mcp serves pipeline status, step logs and waiting for results to coding agents over the Model Context Protocol. See MCP Server for Coding Agents for setup and the available tools.

# Register the server with Claude Code
claude mcp add crow -- crow mcp

Agent Management

# List organization agents
crow org agent ls <org-name>

# Add an organization agent
crow org agent add <org-name> --name "my-agent"

# Show agent details
crow org agent show <org-name> --agent-id <agent-id>

# Remove an organization agent
crow org agent rm <org-name> --agent-id <agent-id>

Global Agent Management

Requires admin privileges.

# List all agents (admin only)
crow admin agent ls

# Show agent details (admin only)
crow admin agent show <agent-id>

# Remove an agent (admin only)
crow admin agent rm <agent-id>

User Management

Requires admin privileges. See instance roles for the available roles.

# List all users
crow admin user ls

# Show user details
crow admin user show <username>

# Add a new user, optionally with instance roles (repeatable)
crow admin user add <username> --role operator

# Replace the instance roles of a user, or remove them
crow admin user update <username> --role operator --role auditor
crow admin user update <username> --no-roles

# Remove a user
crow admin user rm <username>

--role replaces the user’s roles, so a role mapped from the identity provider that is not listed is removed. A mapped role can only be listed when the user already holds it.

Repository Artifacts

# List the artifacts of a repository
crow repo artifact ls <repo>
# Download an artifact
crow repo artifact download --output dist.tar.zst <repo> <artifact-id>
# Remove an artifact
crow repo artifact rm <repo> <artifact-id>
# Remove all artifacts of a repository
crow repo artifact purge <repo>

See Artifacts for details.

Build Cache Limits

Viewing requires the maintenance:read permission, changes need maintenance:write. A user is addressed by their login, an organization by its name or ID. See Caching for how the limits apply.

# List the caches and limits of all users and organizations
crow admin cache ls

# Show the caches, limits and per-repository usage of one user or organization
crow admin cache show <org-or-user>

# Set a size limit, a monthly egress limit and a retention; omitted limits keep their value
crow admin cache set <org-or-user> --max-size 20GiB --max-egress 100GiB --ttl 14d

# Return a limit to the server default, or lift it
crow admin cache set <org-or-user> --max-size default --max-egress unlimited

# Delete all caches of a user or organization
crow admin cache purge <org-or-user>

# Shorten the artifact retention, or refuse new artifact uploads
crow admin cache set <org-or-user> --artifact-retention 7d
crow admin cache set <org-or-user> --artifacts-disabled

# Delete all artifacts of a user or organization
crow admin cache purge --artifacts <org-or-user>

# Remove expired caches and enforce the size limits now
crow admin cache cleanup

Getting Help

# Show all commands
crow --help

# Show help for a specific command
crow repo --help
crow pipeline start --help