Skip to content
The Box CI CLI -- https://boxci.dev
TypeScript Shell JavaScript
Branch: master
Clone or download
Latest commit bb57398 Oct 9, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
scripts first commit Sep 9, 2019
src
test first commit Sep 9, 2019
.gitignore first commit Sep 9, 2019
.npmignore 0.0.1-beta.0 release (#1) Oct 9, 2019
README.md 0.0.1-beta.0 release (#1) Oct 9, 2019
package-lock.json first commit Sep 9, 2019
package.json 0.0.1-beta.0 release (#1) Oct 9, 2019
tsconfig.json first commit Sep 9, 2019
webpack.config.js first commit Sep 9, 2019

README.md

Box CI

This is the open-source Box CI CLI

This 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

> npm run build
> npm link

Usage

Print documentation

> boxci

Run a build

> boxci 'your build command' [Options]

Note

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       Project ID
-p
                Find on the project page on https://boxci.dev


--key           Project secret key
-k
                Find on the project page on https://boxci.dev

Optional

--label         Add a label to this build run
-l
                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        Do not display the build command output in the terminal.
-s
                Note, output will still be streamed to boxci.dev and
[false]         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     Do not show emojis in boxci messaging.
-ne
                As above, this does not affect output from your build commands.
[false]         If you want to stop your build commands outputting emojis,
                you will have to configure them appropriately.


--no-spinners   Do not show spinners in boxci messaging.
-ns
                As above, this does not affect output from your build commands.
[false]         If you want to stop your build commands showing spinners,
                you will have to configure them appropriately.

Advanced

--retries       Max retries for requests to the service.
-r
                Minimum 0 Maximum 100. If the retry count is exceeded,
[10]            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
You can’t perform that action at this time.