README
¶
Bitrise CLI
Bitrise CLI is the workflow runner that powers Bitrise builds. It's the component that runs inside build machines and execute steps defined in bitrise.yml.
It's also useful as a standalone dev tool in your local environment. You can:
- quickly validate your
bitrise.ymlchanges before pushing a commit (bitrise yml validate) - run CI workflows locally (
bitrise local run workflow_name) - run the workflow editor in
localhostand edit your configs and pipelines visually (bitrise :workflow-editor) - perform various other tasks (for a full list run
bitrise help)
Install
There are multiple ways to install Bitrise CLI:
- Homebrew:
brew install bitrise - Nix: available as
bitrisein nixpkgs, runnix-shell -p bitriseor your preferred configuration method. - Download a pre-built binary from the releases page
- There might be other community-maintained packages
You can enable shell completion for the bitrise local run command: https://blog.bitrise.io/workflow-id-completion
Building from source
Set up the right Go version indicated by the go.mod file, then run go install .
Documentation
CLI documentation is part of the main Bitrise docs. Relevant sections:
Tutorials and Examples
You can find examples in the _examples folder.
If you're getting started you should start with _examples/tutorials,
this should guide you through the basics, while you'll already use bitrise (requires installed bitrise).
You can find a complete iOS sample project at: https://github.com/bitrise-io/sample-apps-ios-with-bitrise-yml
Commands
app — List, inspect, and manage apps.
| Command | Description |
|---|---|
app create |
Register a new app on Bitrise |
app list |
List apps the authenticated user can access |
app view |
Show details of a single app |
auth — Manage the Bitrise access token
| Command | Description |
|---|---|
auth login |
Save a Bitrise access token |
auth logout |
Remove the saved access token |
auth status |
Show whether an access token is configured and where it came from |
build — Trigger, list, and inspect builds.
| Command | Description |
|---|---|
build abort |
Abort a running or queued build |
build list |
List builds for an app |
build log |
Print the build log |
build trigger |
Start a new build |
build view |
Show details of a single build |
build watch |
Stream logs for a running build |
build yml |
Print the bitrise.yml a specific build ran with |
config — Manage CLI configuration (defaults persisted to a YAML file).
| Command | Description |
|---|---|
config get |
Print the value of a single config key |
config list |
List the values currently saved in the global config file |
config path |
Print the absolute path of the global config file |
config set |
Set a config key and save the global config file |
config unset |
Remove a config key and save the global config file |
local — Run and manage Bitrise workflows on the local host.
| Command | Description |
|---|---|
local init |
Init bitrise config. |
local run |
Runs a specified Workflow. |
local setup |
Setup the current host. Install every required tool to run Workflows. |
local tools catalog |
List officially supported tools |
local tools info |
Show information about installed or active tools. |
local tools install |
Install a specific tool version |
local tools latest |
Query the latest version of a tool |
local tools setup |
Install tools from version files or bitrise.yml |
local tools versions |
List available versions for a supported tool |
local workflows |
List of available workflows in config. |
plugin — Plugin handling.
| Command | Description |
|---|---|
plugin delete |
Delete bitrise plugin. |
plugin info |
Installed bitrise plugin's info |
plugin install |
Install bitrise plugin. |
plugin list |
List installed bitrise plugins. |
plugin update |
Update bitrise plugin. If <plugin_name> not specified, every plugin will be updated. |
rde — Manage Bitrise Remote Dev Environments (sessions, templates, …)
| Command | Description |
|---|---|
rde claude |
Create an RDE session and attach to Claude Code |
rde machine-type list |
List machine types compatible with a given stack |
rde saved-input create |
Create a new saved input |
rde saved-input delete |
Delete a saved input |
rde saved-input list |
List saved inputs for the authenticated user |
rde saved-input update |
Update a saved input's value and/or secret flag |
rde saved-input view |
Show details of a single saved input |
rde session create |
Create a new RDE session |
rde session delete |
Permanently delete a session in any state (running sessions are stopped and discarded) |
rde session delete-terminated |
Permanently delete every terminated session in the workspace |
rde session diff |
Compare a session's template snapshot with the current template |
rde session download |
Download a file or directory from a session |
rde session exec |
Run a command on a session over SSH |
rde session list |
List RDE sessions in the workspace |
rde session logs |
Print a session's warmup or startup logs |
rde session notifications |
List notifications emitted by a session |
rde session open-vnc |
Open a session's VNC endpoint in the OS-default viewer |
rde session restore |
Restore a terminated session (re-provisions its VM from the persistent disk) |
rde session terminate |
Terminate a running session but keep it for a later restore |
rde session update |
Update a session's name, description, auto-terminate duration, or labels |
rde session upload |
Upload a local file or directory into a session |
rde session view |
Show details of a single session |
rde session vnc |
Print VNC connection details, or forward the endpoint to a local port |
rde stack list |
List machine stacks |
rde template create |
Create a new RDE template from a JSON spec file |
rde template delete |
Delete an RDE template |
rde template list |
List RDE templates in the workspace |
rde template update |
Update an existing RDE template from a JSON spec file |
rde template view |
Show details of a single template |
rde usage |
Show the workspace's active session and resource usage |
stack — Manage build stacks.
| Command | Description |
|---|---|
stack list |
List available stacks and their machine configurations |
step — Manage steps.
| Command | Description |
|---|---|
step inputs |
List inputs of a step version |
step list-cached |
List all the cached steps |
step preload |
Makes sure that Bitrise CLI can be used in offline mode by preloading Bitrise maintaned Steps. |
step search |
Find steps by name, description, or tags |
step share audit |
Validates the step collection. |
step share create |
Create your change - add it to your own copy of the collection. |
step share finish |
Finish up. |
step share start |
Preparations for publishing. |
user — Create and manage your Bitrise account.
| Command | Description |
|---|---|
user create |
Create a new Bitrise account |
user me |
Show the currently authenticated user |
yml — Work with bitrise.yml files.
| Command | Description |
|---|---|
yml get |
Print the bitrise.yml stored on Bitrise |
yml merge |
Resolves includes in a modular bitrise.yml and merges included config modules into a single bitrise.yml file. |
yml update |
Upload a new bitrise.yml to Bitrise |
yml validate |
Validates a specified bitrise config. |
Other commands
| Command | Description |
|---|---|
api |
Make an authenticated request to the Bitrise API |
envman |
Runs an envman command. |
update |
Updates the Bitrise CLI. |
version |
Prints the version |
Tooling support & JSON output format
bitrise CLI commands support a --format=[format] parameter.
This is intended mainly for tooling support, by adding --format=json you'll
get a JSON formatted output on Standard Output.
Every error, warning etc. message will go to StdErr; and on the StdOut you should only get the valid JSON output.
An example calling the version command:
$ bitrise version --format=json
Will print {"version":"1.2.4"} to the Standard Output (StdOut).
Share your Step
You can use your own Step as you can see in the _examples, even if it's
not yet committed into a repository, or from a repository directly.
If you would like to share your awesome Step with others
you can do so by calling bitrise step share and then following the
guide it prints.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
analyticstest
Package analyticstest provides a no-op analytics.Tracker for tests — either wired via cmdutil.SetTracker (command packages whose RunE calls cmdutil.LogCommandParameters) or passed directly to a constructor expecting a Tracker (e.g.
|
Package analyticstest provides a no-op analytics.Tracker for tests — either wired via cmdutil.SetTracker (command packages whose RunE calls cmdutil.LogCommandParameters) or passed directly to a constructor expecting a Tracker (e.g. |
|
app
Package app implements the `bitrise app` command group: list, view, and create apps on Bitrise.
|
Package app implements the `bitrise app` command group: list, view, and create apps on Bitrise. |
|
build
Package build implements the `bitrise build` command group: trigger, list, view, log, watch, abort, and yml operations on Bitrise builds.
|
Package build implements the `bitrise build` command group: trigger, list, view, log, watch, abort, and yml operations on Bitrise builds. |
|
cmdtest
Package cmdtest is the shared test harness for rde command groups.
|
Package cmdtest is the shared test harness for rde command groups. |
|
cmdutil/picker
Package picker is a small reusable arrow-key list selector built on bubbletea.
|
Package picker is a small reusable arrow-key list selector built on bubbletea. |
|
purr
Package purr implements the `bitrise purr` easter egg: an animated ASCII cat mascot with a rainbow-shimmer message.
|
Package purr implements the `bitrise purr` easter egg: an animated ASCII cat mascot with a rainbow-shimmer message. |
|
rde/claude
Package claude wires the `bitrise rde claude` command: spin up an RDE session and attach straight into Claude Code.
|
Package claude wires the `bitrise rde claude` command: spin up an RDE session and attach straight into Claude Code. |
|
rde/savedinput
Package savedinput wires `bitrise rde saved-input` subcommands.
|
Package savedinput wires `bitrise rde saved-input` subcommands. |
|
internal
|
|
|
api
Package api holds the business-logic layer for the generic, curl-like passthrough to the Bitrise API exposed by the `api` command.
|
Package api holds the business-logic layer for the generic, curl-like passthrough to the Bitrise API exposed by the `api` command. |
|
app
Package app holds the business-logic layer for app operations.
|
Package app holds the business-logic layer for app operations. |
|
auth
Package auth persists and reads the Bitrise access token.
|
Package auth persists and reads the Bitrise access token. |
|
baseurl
Package baseurl validates URLs that will carry credentials (a bearer token, a login password) to whatever host they name.
|
Package baseurl validates URLs that will carry credentials (a bearer token, a login password) to whatever host they name. |
|
bitriseapi
Package bitriseapi is a minimal client for the Bitrise API (https://api.bitrise.io/v0.1).
|
Package bitriseapi is a minimal client for the Bitrise API (https://api.bitrise.io/v0.1). |
|
build
Package build holds the business-logic layer for build operations.
|
Package build holds the business-logic layer for build operations. |
|
cache
Package cache provides a lightweight in-memory app title→slug and workspace name→slug cache for CLI lookups.
|
Package cache provides a lightweight in-memory app title→slug and workspace name→slug cache for CLI lookups. |
|
config
Package config persists and reads the CLI's layered settings: a global config file and a per-directory override file, both layered underneath the pre-existing ~/.bitrise/config.json store, which stays authoritative when present (see resolve.go).
|
Package config persists and reads the CLI's layered settings: a global config file and a per-directory override file, both layered underneath the pre-existing ~/.bitrise/config.json store, which stays authoritative when present (see resolve.go). |
|
filelock
Package filelock provides a simple, cross-process exclusive lock backed by a sentinel file, for serializing a read-modify-write sequence on some other file across separate CLI invocations.
|
Package filelock provides a simple, cross-process exclusive lock backed by a sentinel file, for serializing a read-modify-write sequence on some other file across separate CLI invocations. |
|
oauth
Package oauth implements the browser-based OAuth login flow (PKCE, RFC 8252 loopback redirect) and its background token refresh: authorize -> code -> JWT (WorkOS) -> PAT (monolith OIDC exchange, RFC 8693, same call the MCP server makes).
|
Package oauth implements the browser-based OAuth login flow (PKCE, RFC 8252 loopback redirect) and its background token refresh: authorize -> code -> JWT (WorkOS) -> PAT (monolith OIDC exchange, RFC 8693, same call the MCP server makes). |
|
rde
Package rde is the business-logic layer over internal/rdeapi: CLI-stable snake_case DTOs, validation, and wait loops.
|
Package rde is the business-logic layer over internal/rdeapi: CLI-stable snake_case DTOs, validation, and wait loops. |
|
rde/localsession
Package localsession persists `rde claude` session records locally so they can be resumed later (`rde claude --resume` / `--continue`).
|
Package localsession persists `rde claude` session records locally so they can be resumed later (`rde claude --resume` / `--continue`). |
|
rdeapi
Package rdeapi is the HTTP client for the Bitrise Remote Dev Environments API (https://api.bitrise.io/rde).
|
Package rdeapi is the HTTP client for the Bitrise Remote Dev Environments API (https://api.bitrise.io/rde). |
|
resolve
Package resolve maps a user-supplied app or workspace name/slug to the canonical slug.
|
Package resolve maps a user-supplied app or workspace name/slug to the canonical slug. |
|
stack
Package stack holds the business-logic layer for stack operations.
|
Package stack holds the business-logic layer for stack operations. |
|
stringutil
Package stringutil holds small string helpers shared across the internal packages.
|
Package stringutil holds small string helpers shared across the internal packages. |
|
style
Package style holds the lipgloss-backed semantic styles used by human renderers.
|
Package style holds the lipgloss-backed semantic styles used by human renderers. |
|
user
Package user holds account creation and email/password sign-in against app.bitrise.io's Rails-Devise JSON endpoints (POST /users for signup, /users/sign_in for sign-in, /me/profile/security/user_auth_tokens to mint a PAT).
|
Package user holds account creation and email/password sign-in against app.bitrise.io's Rails-Devise JSON endpoints (POST /users for signup, /users/sign_in for sign-in, /me/profile/security/user_auth_tokens to mint a PAT). |
|
webclient
Package webclient is a short-lived HTTP client for app.bitrise.io's Rails-Devise endpoints (signup, email/password sign-in).
|
Package webclient is a short-lived HTTP client for app.bitrise.io's Rails-Devise endpoints (signup, email/password sign-in). |
|
workspace
Package workspace holds the rules for picking a workspace when the user didn't name one.
|
Package workspace holds the rules for picking a workspace when the user didn't name one. |
|
yml
Package yml holds the business-logic layer for bitrise.yml operations.
|
Package yml holds the business-logic layer for bitrise.yml operations. |
|
gendocs
command
Command gendocs renders the bitrise command tree into a markdown reference, one file per command, under docs/cli, and refreshes the command overview embedded in README.md.
|
Command gendocs renders the bitrise command tree into a markdown reference, one file per command, under docs/cli, and refreshes the command overview embedded in README.md. |
Click to show internal directories.
Click to hide internal directories.