Bitrise CLI: running a Bitrise workflow on your own machine

The same binary runs hosted builds and your laptop

The Bitrise CLI is not a separate local emulator bolted onto the hosted product. It is the component that runs inside build machines and executes the steps defined in bitrise.yml, and the same program is documented as useful as a standalone development tool in a local environment. That equivalence is the whole design point and it is the reason the local commands are trustworthy. A workflow that passes locally is running the same step definitions, in the same order, with the same configuration parsing, so a failure you reproduce locally is a failure you can debug with a real shell rather than through build log output. The project description is narrower than the toolset, calling it a runner for automations on a Mac or Linux machine, and the command groups confirm the wider surface: app, auth, build, config, local, plugin and rde. The local group is the one for developers, the build group is the one for talking to the hosted service, and both live in the same binary.

Validating bitrise.yml before the commit lands

The cheapest thing the CLI does for you is refuse a broken configuration file. The README lists it first among the local uses: quickly validate your bitrise.yml changes before pushing a commit. The command is short:

bitrise yml validate

The point is not stylistic. A bitrise.yml is a YAML file that other tools consume, and a mistake in it fails at the point where a hosted build picks it up, which is usually a broken pipeline for the whole team rather than for you. Running the validator locally moves that failure to your own machine, before anyone else sees it. The workflow editor is the other half of the same idea, and it runs in a browser on localhost:

bitrise :workflow-editor

That command opens a visual editor for your configs and pipelines, which matters for a format that is a graph of steps with inputs, triggers and dependencies rather than a flat list of shell commands. Editing that in a text editor is possible and unpleasant. The generated workflow list is also available locally, and the local workflows command lists what is available in the current config, which is a quick way to confirm that the workflow you think you defined is the one the runner will find.

local run executes a named workflow, local setup installs the tools it needs

Running a workflow on your own machine takes a workflow name:

bitrise local run workflow_name

The second half of the local story is the toolchain. A Bitrise workflow calls named tools, a language runtime, a mobile SDK, a package manager, and each step expects a specific version to be present. The local setup command handles that for you, and the description in the command table is blunt about it: setup the current host, install every required tool to run workflows. The local tools group goes further and lets you work with the tool catalogue directly. You can list officially supported tools with local tools catalog, install a specific tool version, query the latest version of a tool, show information about installed or active tools, list available versions for a supported tool, and install tools from version files or bitrise.yml. That last one is the useful one, because it ties the local toolchain to the same version declarations the workflow file carries. local init initialises the bitrise config, and local workflows lists the workflows the config exposes.

The workflow id completion for bitrise local run is documented in a separate blog post, which matters for a workflow name you do not want to type from memory every time.

Talking to the hosted service with the build and auth groups

The CLI is also a client for the hosted Bitrise service, and this is where the app, auth and build command groups sit. The auth group manages the access token, with auth login to save one, auth logout to remove it and auth status to show whether a token is configured and where it came from. That last detail is worth noticing, because the where it came from part suggests more than one source is possible and a status command that tells you the source removes a whole class of confusing failures. The app group registers a new app with app create, lists the apps the authenticated user can access and shows details of a single app. The build group covers the build lifecycle: build trigger to start a new build, build list for an app, build view for details, build log to print the log, build watch to stream logs for a running build, build abort for a running or queued build, and build yml to print the bitrise.yml a specific build ran with. That last command is quietly valuable, because it tells you the configuration a build actually used, which is how you check whether a change you made was the change that ran.

Config and plugin commands, and a global YAML file

Two command groups handle the state that would otherwise be scattered across shell profiles. The config group manages CLI configuration with defaults persisted to a YAML file, and it offers config get for a single key, config set to write one, config unset to remove one, config list to see what is currently saved and config path to print the absolute path of the global config file. That last one is a small command that pays for itself the first time a workflow behaves differently on your machine than on a colleague's, because it tells you exactly which file is in play. The plugin group handles Bitrise plugins with install, list, info, update and delete, and update has a convenient scope, since omitting the plugin name updates every plugin. The rde group is the newest surface and covers Remote Dev Environments, with sessions and templates, a machine type list command for machine types compatible with a given stack, saved input commands for create, delete and list, and an rde claude command that creates a session and attaches to Claude Code. That last command is a clear signal of where the product is heading.

A Go module with a heavy dependency list and a vendored tree

The build setup tells you what you are pulling in. The module path is github.com/bitrise-io/bitrise/v3 and the go.mod file asks for go 1.25.11, so building from source means a recent Go toolchain rather than a system default. The direct dependencies describe the tool's internals plainly. cobra and pflag provide the command tree that produces the grouped subcommands. charmbracelet bubbletea, bubbles and lipgloss are the terminal UI libraries, and termenv and go-colorful handle colour output, which is consistent with a CLI that renders progress and interactive prompts. stepman is the step manager, envman/v2 handles environment variables, and heimdalr/dag provides a directed acyclic graph, which is what a workflow with step dependencies and triggers is. go-git/v5 handles repository operations, retryablehttp and go-version handle network calls and version comparison, and yaml.v2 and yaml.v3 do the configuration parsing. The repository ships a vendor/ directory, and a.golangci.yml for linting plus a.goreleaser.yaml for release builds. The licence field on the repository says MIT, and the last push was on 2026-10-22 with v3.2.1 published on 2026-10-07 and v3.2.0 a few hours earlier the same day.

The Dockerfile and Makefile in the repository are not current practice

Two files in the repository root will mislead you if you read them as instructions. The Dockerfile starts FROM golang:1.11, which is many major Go releases behind the 1.25.11 the module now requires, and it installs tooling with go get -u for godep, errcheck and golint, a pattern that no longer works with module mode. It also runs bitrise setup and points stepman at a step library repository. The docker-compose.yml in the root is a minimal three-line file that builds from the current directory and mounts it into a legacy GOPATH path. The Makefile is clearer about its own scope, since its first comment says it is intended to be used only for local testing of container related integration tests and that everything else CI related is in the bitrise.yml. The same file holds the docs target, which runs a Go program to generate the CLI documentation, and a docs-check target that fails when the generated docs in docs/cli and README.md are out of date. That last target is the reason the command tables in the README are marked as generated by make docs, and it is a good sign about the project's discipline even where the container files have not been kept current.

Editorial conclusion

The Bitrise CLI is a good fit for a mobile or backend team already on Bitrise who wants to catch a broken bitrise.yml before pushing, or to reproduce a failing build step on a laptop with the same runner semantics, and the local tools commands remove most of the excuse not to try. It is the wrong tool for a team on GitHub Actions or another CI system, since the configuration format is Bitrise specific, and it is the wrong tool if your pipeline needs only a few shell commands, since a plain Makefile will do that job with far less setup. Before adopting it, install the toolchain your workflow expects with bitrise local setup rather than assuming your machine matches the build image, read the known local difference between the local runner and the hosted build machine, and pin the CLI version, since releases arrive often, with v3.2.1 dated 2026-10-07 and the last push on 2026-10-22.

Frequently asked questions

Official sources

1. bitrise-io/bitrise on GitHub
2. License: MIT
3. Project website
4. README
5. Releases