Skip to content
agentctlv1

Installation

This guide installs the agentctl 0.3 Rust CLI with workflow API v1 from crates.io, reviewed source, or a locally built OCI image.

Prerequisites

Section titled “Prerequisites”
  • Rust 1.88, as pinned by rust-toolchain.toml
  • Git and a supported local checkout for source builds
  • Optional: Docker or Podman for the container path

Install from crates.io

Section titled “Install from crates.io”
cargo install --locked agentctl-cli
agentctl version

The crates.io package is named agentctl-cli; the installed executable is named agentctl.

Install from source

Section titled “Install from source”

From the agentctl repository root, run:

cargo install --locked --path crates/agentctl-cli
agentctl version

The install compiles the Rust CLI and writes it to Cargo’s binary directory. It makes dependency network requests during the build, writes no runtime database, and needs no provider credential.

If you only want a repository-local binary, use:

cargo build --locked -p agentctl-cli
./target/debug/agentctl version

Build a release binary

Section titled “Build a release binary”

From the repository root:

cargo build --release --locked -p agentctl-cli
./target/release/agentctl version

cargo xtask package also produces the binary, shell completions, license, README, and SHA-256 manifest beneath dist/. The package is local build output, not a published release.

Build the container image

Section titled “Build the container image”

From the repository root, with Docker:

docker build --tag agentctl:local --file Containerfile .
docker run --rm agentctl:local version --output json --color never

The build downloads Rust dependencies. The version command makes no provider call and writes no state. The resulting image runs as UID/GID 65532 with agentctl as its entrypoint. Read the container contract before executing a workflow.

Verify the installation

Section titled “Verify the installation”

From the repository root:

agentctl check examples/v1/hello.yaml
agentctl plan examples/v1/hello.yaml

Expected evidence includes valid: hello, task order greet, and FullyPredictable. These commands do not create a runtime database.

Upgrade safely

Section titled “Upgrade safely”

The workflow API is agentctl.dev/v1. Pin the CLI or image version, read compatibility and limitations, back up the SQLite database with its WAL files, then validate workflows before replacing a binary. agentctl update explains supported update paths but does not modify the installation.

Next step

Section titled “Next step”

Continue with Getting started.

Canonical source: docs/guides/INSTALLATION.md. Verified against agentctl commit 2aeaa88fba71162206b5f08f5bda4f0150247e4f.