Box CI CLI Documentation

The Box CI CLI is how your build machines talk to the Box CI service. It acts as a wrapper around your existing build commands, and talks to Box CI to create a build run and stream logs there.

It's open source so you know exactly what is running on your machines.

Install

As a global package with npm

> npm i -g boxci

Or build from source

> git clone git@github.com:boxci/boxci.git > cd ./boxci; > npm run build && npm link

Now boxci is available on your machine as a global command

Note that for the initial beta release, NodeJS and npm are required dependencies of boxci. They must be present on your build machines.

Why? boxci is written in TypeScript, and so NodeJS provides both a natural runtime but also a package manager (npm) that works on every OS. This makes it a very convenient option for the initial beta release.

The eventual goal is to distribute boxci native binaries via the relevant package managers for each major OS. Then, there will be no dependencies at all.

I know that needing to install NodeJS to make boxci work may be a dealbreaker, or at best inconvenient. Shipping the native binaries is a priority! If it's a showstopper for you, please send an email to contact@boxci.dev or give me a shout on twitter @davnicwil

Usage

Print documentation

> boxci

Run a build

> boxci 'your build command' [Options]

The string in 'your build command' is just your existing build command.

e.g 'sh ./build.sh', 'make app', 'npm test && npm run build', etc.

Options

Required

--project
-p
Project ID
Find on the project page
--key
-k
Project secret key
Find on the project page

Optional

--label
-l
Add a label to this build run
Provide the label name and value with the syntax --label key,value To provide multiple labels, repeat the option for each label. There is a limit of 32 characters for label names and 512 characters for label values.
--silent
-s
[ false ]
Do not display the build command output in the terminal.
Note, output will still be streamed to boxci.dev and displayed on the build page. This option is only intended for convenience if you don't wish to see the ouput in the terminal when you run boxci.
boxci has no control over the output of your build commands. If you want to silence some or all of their output, you have to configure the commands appropriately.
--no-emojis
-ne
[ false ]
Do not show emojis in boxci messaging.
As above, this does not affect output from your build commands. If you want to stop your build commands outputting emojis, you will have to configure them appropriately.
--no-spinners
-ns
[ false ]
Do not show spinners in boxci messaging.
As above, this does not affect output from your build commands. If you want to stop your build commands showing spinners, you will have to configure them appropriately.

Advanced

--retries
-r
[ 10 ]
Max retries for requests to the service.
Minimum 0 Maximum 100. If the retry count is exceeded, boxci exits and the build will be cancelled. You may wish to use this if your network conditions are particularly unreliable.

Config File - boxci.json

All options above can also be defined in a JSON config file named `boxci.json` in the same directory you run the boxci command from.

The format of boxci.json is as follows

{ "project": "QWE123", "key": "ABCDEF123456", "labels": [ { "name": "label-one", "value": "value-one" }, { "name": "label-two", "value": "value-two" } ], "silent": false, "noEmojis": false, "noSpinners": false, "retries": 10 }

All options in boxci.json are optional. For the required options project and key, it's only required that they are provided either in boxci.json or directly to the boxci command.

Examples

Run a build command and stream logs to project QWE123

> boxci 'npm run build' \ --project QWE123 \ --key ABCDEFG123456

Run as many commands you want, any valid shell commands work fine

> boxci 'cd ..; npm run test && npm run build' \ --project QWE123 \ --key ABCDEFG123456

Or for longer builds, just run a script

> boxci 'sh ./build.sh' \ --project QWE123 \ --key ABCDEFG123456

Add labels to a build run to attach meaningful metadata to it

> boxci 'sh ./build.sh' \ --project X01X01 \ --key ABCDEFG123456 \ --label git-commit,$(git rev-parse HEAD) \ --label git-branch,$(git rev-parse --abbrev-ref HEAD) \ --label build-machine,my-laptop

Provide some config via boxci.json

For convenience you can provide some static config in boxci.json That way you don't have to type the config every time you run boxci BE AWARE - you probably do not want to commit this file to source control if it contains your key, rather just keep it on your local machine for convenience --- boxci.json --- { "project": "X01X01", "key": "ABCDEFG123456", "labels:: [{ "name": "build-machine", "value": "my-laptop" }] } You can now run boxci from the same directory and it will work without passing any options on the command line, because both 'project' and 'key' are defined in boxci.json > boxci 'your build command' You can also supply extra options, in addition to the ones defined in boxci.json, for example dynamic labels or ones you only want to use in certain circumstances like --silence or --no-spinners > boxci 'your build command' \ --label git-commit,$(git rev-parse HEAD) \ --label git-branch,$(git rev-parse --abbrev-ref HEAD) \ --silence \ --no-spinners