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.yml changes before pushing a commit (bitrise yml validate)
• run CI workflows locally (bitrise local run workflow_name)
• run the workflow editor in localhost and 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 bitrise in nixpkgs, run nix-shell -p bitrise or 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:

• Workflows and Pipelines
• Bitrise CLI local use

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.