Skip to main content

The build-cli User Guide

build-cli is based on the Build API, which has now been deprecated and will be removed from service in August 2018. Please upgrade to build-cli’s successor, imp-central-api.

build-cli is a suite of command-line tools which allows you to interact with Electric Imp’s Build API. Build provides an interface to the Electric Imp impCloud™ to help you manage a imp-based development projects using your own workflow and tools. You should familiarize yourself with Build’s status and error codes, and methodology before using build-cli.

Current Version: 0.3.5

Installing build-cli

In order to run build-cli, you require Node.js and its companion, Node Package Manager (NPM). For Linux-based hosts, these can be installed using the distribution’s chosen package manager. The Node.js website has installers for Windows. For Mac OS X, we recommend using the Brew package manager: install this as per the instructions on the site and then run brew install node.

build-cli was constructed using Node.js 6.2.2, but it should work with any version from 4.2.1 upwards.

Install build-cli by entering the following command in a terminal:

npm install -g build-cli

This will install build-cli and its dependencies. After installation, the imp program will be available from your command prompt. From there you should be able to use all of the tools.

Updating build-cli

Enter the following to update build-cli and its components at any time:

npm update -g build-cli

Dependencies

build-cli makes use of a number of third-party Node.js modules, including cli-prompt, cli-table, cli-spinner, commander, color and osenv. It also makes use of build-api, a Node.js-based application that connects build-cli to the Build API. All of these dependencies should be resolved and any missing components added when you install build-cli.

Source Code

build-cli source code can be viewed here.

build-cli Tools

build-cli provides the following tools, each accessed via the command line with the command imp:

  • devices — List and manage devices
  • init — Create an empty imp project, or reinitialize an existing one
  • log — Display logs from the specified device
  • setup — Sets your global API key
  • migrate — Migrates a model from one account to another
  • models — List and manage models
  • pull — Fetch latest build from the server
  • push — Update the build, and push code to developer devices

To view help information for each tool, you can either add the -h or help option to the command invoking the tool, or enter help [toolname] to display help for the named tool.

Initializing build-cli

The first time you use build-cli, you should run its setup tool, setup from your home directory (~):

imp setup

All build-cli tools are triggered by using imp at the command prompt followed by the tool’s name and parameters.

When you run setup, it will first ask for your Build API key. This will have been provided to you by your project manager or, if you are using your own Electric Imp account, by generating a key of your own using the IDE. Log into the IDE, click on the ‘username’ menu at the top right and select ‘Build API Keys’. This will open a panel in which you can click ‘Add Key’ to generate a key for your account. In the space provided enter a description and then click on the ‘Save’ button. The key will now appear, and you can highlight and copy it. Click ‘Done’ to hide the panel.

However you obtain your Build API key, paste it at the setup prompt. build-cli will now create a .impconfig file in your home directory. This file is used to store your Build API ‘globally’ — it is used for all Build API requests that are not specific to a project.

You can optionally pass an alternative Build API URL to setup: just use the -u or --url option followed by the new URL. This can be used to connect to private impCloud installations.

You are now ready to begin using build-cli.

How to Use build-cli

build-cli is designed to work with one model at a time — called the ‘project’ — and stored locally in its own directory or folder. It is important not to use your home directory. After creating a new project directory (mkdir <directory_name>) you should enter that directory (cd <directory_name>) and then run imp init to initialize the project folder.

When you first connect to an impCloud using build-cli’s init tool, you are prompted to re-enter your Build API key, with the default global value (see above) presented in brackets. Whenever build-cli has a default value it can use, it displays the value in brackets at the prompt; just hit Enter or Return to use the default.

init now asks for the name of a new or existing model. This model becomes your current project, and its agent and device code are now downloaded to local files for editing. The model name is used to set default filenames for these two source code files; again, hit Enter to accept the default or key in new names.

If you provide a model name that doesn’t match that of an existing model, a new model will be created with the name you entered. No code files will be created locally — you need to do this manually.

Finally, init creates a local .impconfig file to record the Build API associated with this project, the ID of the project’s model, the agent and device source code filenames, and an array of IDs of devices already associated with the model.

You can now write your imp-based application across both agent and device code files and, when you are ready, upload the code back to the public or a private impCloud (depending on the account whose Build API key you provided). You upload fresh changes using the push tool.

build-cli assumes you will have a separate directory for each of your projects. There can be only one project configuration file (.impconfig) per directory, and this governs the behavior of project-specific tools, such as push. Change your working directory to change the project you are currently working on.

For example, you are working in the directory ~/counter on the device code stored in the file counter.device.nut. You save your changes and then use cd ~/blast to switch to the directory ~/blast with the intention of making some modifications to that project too. However, you remember you have not pushed the updated Counter code to the Electric Imp impCloud. If you run imp push straight away, you will push any changes you have made to the Blast source (none as yet) not the Counter source. To push your counter updates, you must first switch back to the ~/counter directory and then run imp push.

You may choose to assign another device to the project: use the devices tool to get a list of devices associated with your account, highlight and copy the device ID of the unit you want to use to test the project code, and then run device again, this time with the -a option followed by the device ID to assign the specified hardware to the project. Again, this associates the device with the project specified by the .impconfig file in your current working directory.

To monitor the effect of the code on the hardware, you can use the log tool to stream logging data in real time from a specified device to your command line.

Collaboration

You may be working with colleagues on the same project. They too will have a directory to store a local copy of the project — everyone needs to use the pull tool to update their version of the project with any changes that have been made since they last pushed their code to the Electric Imp impCloud.

For example, Terry makes changes to his local copy of Counter. When he is happy with the updates, he runs imp push to update the impCloud.

Now he is joined by a colleague, Yolly. She installs build-cli and initializes her machine as described above. Both Yolly and Terry have Build API keys issued to them by their commissioning organization. Yolly enters her API key when setup prompts her. She now creates a ~/counter directory of her own. She changes into this directory and runs imp new to set the project up as described above. She uses the default API key and enters counter as the model name. init detects that this is an existing model, asks her to confirm that this is the model she means (she replies by entering ‘Y’) and then downloads copies of the source code. She picks up where Terry left off (he is based in Europe, she in Australia) and finally runs imp push to upload the changes she has made.

Terry starts work the next day by running imp pull. This updates his local source files with the changes made by Yolly the night before.

If the project is work you are conducting as a contractor, when you have completed the software, you can transfer it to the organization which commissioned your work using the migrate tool.

In the example above, this use of migrate isn’t necessary — Terry and Yolly were synchronizing their work with their commissioning organizer’s account. Had they been collaborating through Terry’s own public impCloud account, however, Terry would now use migrate to copy the development model over to the project managers account, which might also be in the public impCloud or in a private impCloud.

GitHub

Neither the Build API nor build-cli interface directly with GitHub or other code revision management systems, but by creating an empty repository and cloning it to your local machine; using build-cli’s init at the local repository clone’s location — which copies your agent and device code files locally; and then synchronizing the repository, you can maintain your code in GitHub.

Remember, you will need to synchronize changes made to the online repository and then use push to keep the code on the servers in sync with the code in the repository.

build-cli Command Reference

Devices

The devices tool allows you to list and manage development devices. Use it to obtain a device’s device_id, used by other tools which target specific devices. The tool provides a number of options to narrow the list of devices displayed, including online devices, offline devices and unassigned devices.

Usage

imp devices [options]

Options

  • -h, help — Output usage information
  • -a, add <device_id> — Adds a device to the current project
  • -r, remove <device_id> — Removes a device to the current project
  • -m, --model <modelID/modelName> — List devices assigned to the specified model
  • -c, current — Filters list to only display devices associated with the current project
  • online — Filters list to only display online devices
  • offline — Filters list to only display offline devices
  • assigned — Filters list to only display assigned devices
  • unassigned — Filters list to only display unassigned devices

New

The init tool is used to initialize a project’s own directory, creating a per-project .impconfig file to hold project data based on the values you input and defaults you accept.

If, when requested, you provide a model name that doesn’t match that of an existing model, a new model will be created with the name you entered. No code files will be created locally — you need to do this manually.

Using the options provided, you can re-initialize the .impconfig file, with or without updating the local agent and device source code files.

Usage

imp new [options]

Options

  • -h, help — Output usage information
  • -f, force — Overwrites your existing .impconfig file
  • -k, keep [options] — Prevents code files from being overwritten during initialization. You can specify which files should be protected using the following options:

    • imp new -k — Agent and device code files will not be overwritten
    • imp new -k device — Device code file will not be overwritten
    • imp new -k agent — Agent code file will not be overwritten
  • -g, global — Uses global API key and prevents the API key from being written to .impconfig

Note Previously, build-cli used init to perform this function. The use of init is retained for backwards compatibility.

Log

Use this tool to retrieve and display logs for a specified device, streamed from the device and its agent in real time. The required devices is indicated by passing its device ID after the -d option. Use devices to obtain a given device’s ID. Alternatively, you can enter a device’s name: place it after the -t option.

Usage

imp log [options]

Options

  • -h, help — Output usage information
  • -d, device <device_id> — The device ID you would like to see logs for
  • -t, title <device_id> — The device name you would like to see logs for
  • -l, --list — Present the most recent logs rather than a stream for the specified device

Setup

Use this tool to change the URL of the API you are working with. For example, you might be accessing the Build API in the Electric Imp public impCloud (build.electricimp.com/v4/) while developing a model. When it is complete, you would use setup to switch to the API’s URL within a private impCloud, eg. build.example.com, perhaps for a customer for whom you are developing the code. Because this implicitly involves changing accounts, setup will prompt you for the API key associated with the second account.

Usage

imp setup [options]

Options

  • -h, help — Output usage information
  • -u, url [baseUrl] — Overrides base URL for the API. For example: imp setup -u build.example.com sets the URL used by build-cli to build.example.com

Note This functionality was previously delivered by the command login. This has been replaced by setup.

Migrate

Use this tool to copy a model from one impCloud account to another. Both accounts should be in the same impCloud — for example, the Electric Imp public impCloud — and are identified by their respective Build API keys. To make use of this tool, you will need to re-enter your own Build API key and one for the account which will be receiving your code. If you do not have this, contact the account holder.

migrate will prompt you for the Build API key of your (development) account followed by the name or ID of the model you wish to transfer, with the current project offered as a default. Now enter local device and agent file names (or just Enter to accept the project defaults). migrate will now download the latest build before asking you for the target (production) account’s Build API key and the name or ID of a model (the current project name is offered as a default) which will be send your code. The tool will now upload your code to this model.

Typically, this tool is used to transfer ownership of a development model upon completion to the account of the individual or company which commissioned the software.

Usage

imp migrate [options]

Options

  • -h, help — Output usage information
  • -r, revision [revision] — Pulls the specified revision from development account

Models

The models tool allows you to list and manage development models. Use it to obtain a model’s ID. You can apply a number of filters to narrow the displayed list of models to those which are active (ie. in development and have devices associated with them) and those which are not (ie. have no device associated with them).

Usage

imp models [options]

Options

  • -h, help — Output usage information
  • -d, --device <deviceID> — Lists the model to which the specified device ID is assigned (if any)
  • -d, --device <deviceName> — Lists the model to which the specified device name is assigned (if any)
  • active — Filters list to only display active models
  • inactive — Filters list to only display inactive models

Pull

Use this tool to update your local copy of the current project model’s agent and device code files with any changes that have been made using the IDE — or by other users working with the Build API. You can update your local files with a specific code revision by specifying the revision’s build number after the -r option. If you don’t provide a revision, pull gets the latest version of the code.

You can also use the -d option to update the local list of devices associated with the current project. This may be necessary if you are collaborating with others who may separately update the list of associated devices.

Usage

imp pull [options]

Options

  • -h, help — Output usage information
  • -r, revision <build_number> — Pulls the specified revision
  • -d, devices — Pulls and syncs device list

Push

Use this tool to transfer any changes you have made to your local copy of the current project model’s agent and device code files to an impCloud. This tool will only push code for the model defined by the .impconfig file within the directory from which it is run.

Usage

imp push [options]

Options

  • -h, help — Output usage information

License

build-cli is licensed under the MIT License.

build-cli is based on imp-cli and imp-api by Cat Haines. imp-cli and imp-api are copyright © Cat Haines, 2015. build-cli is copyright © Cat Haines, 2015 and copyright © Electric Imp Inc., 2015-17.