2018-10-19 14:38:50 +00:00
# Balena CLI Documentation
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
This tool allows you to interact with the balena api from the comfort of your command line.
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Please make sure your system meets the requirements as specified in the [README ](https://github.com/balena-io/balena-cli ).
2017-01-18 15:57:52 +00:00
2018-03-12 19:06:21 +00:00
## Install the CLI
2015-04-16 13:34:40 +00:00
2018-12-27 20:33:12 +00:00
### Dependencies
Before installing the Balena CLI from npm, make sure you have the following dependencies installed:
* make
* g++ compiler
* Python 2.7
* git
For example, to install these packages on a Debian-based Linux operating systems:
```
$ sudo apt-get install g++ make python git --yes
```
**NOTE**: If you are installing the stand-alone binary CLI, you will not need to install these dependencies.
2018-03-12 19:06:21 +00:00
### Npm install
2015-04-16 13:34:40 +00:00
2018-03-12 19:06:21 +00:00
The best supported way to install the CLI is from npm:
2018-10-19 14:38:50 +00:00
$ npm install balena-cli -g --production --unsafe-perm
2018-03-12 19:06:21 +00:00
`--unsafe-perm` is only required on systems where the global install directory is not user-writable.
This allows npm install steps to download and save prebuilt native binaries. You may be able to omit it,
especially if you're using a user-managed node install such as [nvm ](https://github.com/creationix/nvm ).
### Standalone install
Alternatively, if you don't have a node or pre-gyp environment, you can still install the CLI as a standalone
binary. **This is in experimental and may not work perfectly yet in all environments** , but works well in
initial cross-platform testing, so it may be useful, and we'd love your feedback if you hit any issues.
To install the CLI as a standalone binary:
2018-10-19 14:38:50 +00:00
* Download the latest zip for your OS from https://github.com/balena-io/balena-cli/releases.
* Extract the contents, putting the `balena-cli` folder somewhere appropriate for your system (e.g. `C:/balena-cli` , `/usr/local/lib/balena-cli` , etc).
* Add the `balena-cli` folder to your `PATH` . (
2018-03-12 19:06:21 +00:00
[Windows instructions ](https://www.computerhope.com/issues/ch000549.htm ),
[Linux instructions ](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix ),
[OSX instructions ](https://stackoverflow.com/questions/22465332/setting-path-environment-variable-in-osx-permanently ))
2018-10-19 14:38:50 +00:00
* Running `balena` in a fresh command line should print the balena CLI help.
2018-03-12 19:06:21 +00:00
To update in future, simply download a new release and replace the extracted folder.
Have any problems, or see any unexpected behaviour? Please file an issue!
## Getting started
2018-10-19 14:38:50 +00:00
Once you have the CLI installed, you'll need to log in, so it can access everything in your balena account.
2018-03-12 19:06:21 +00:00
To authenticate yourself, run:
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
$ balena login
2015-04-16 13:34:40 +00:00
2018-03-12 19:06:21 +00:00
You now have access to all the commands referenced below.
2015-04-16 13:34:40 +00:00
2017-04-26 13:16:06 +00:00
## Proxy support
The CLI does support HTTP(S) proxies.
You can configure the proxy using several methods (in order of their precedence):
2018-10-19 14:38:50 +00:00
* set the `BALENARC_PROXY` environment variable in the URL format (with protocol, host, port, and optionally the basic auth),
* use the [balena config file ](https://www.npmjs.com/package/balena-settings-client#documentation ) (project-specific or user-level)
2017-04-26 13:16:06 +00:00
and set the `proxy` setting. This can be:
* a string in the URL format,
* or an object following [this format ](https://www.npmjs.com/package/global-tunnel-ng#options ), which allows more control,
* or set the conventional `https_proxy` / `HTTPS_PROXY` / `http_proxy` / `HTTP_PROXY`
environment variable (in the same standard URL format).
2015-04-16 13:34:40 +00:00
# Table of contents
2018-04-04 12:42:57 +00:00
- Api keys
- [api-key generate <name> ](#api-key-generate-name- )
2015-04-16 13:34:40 +00:00
- Application
2018-03-20 17:43:26 +00:00
- [app create <name> ](#app-create-name- )
2015-07-07 22:01:25 +00:00
- [apps ](#apps )
2018-03-20 17:43:26 +00:00
- [app <name> ](#app-name- )
- [app restart <name> ](#app-restart-name- )
- [app rm <name> ](#app-rm-name- )
2015-04-16 13:34:40 +00:00
- Authentication
2015-11-11 12:45:38 +00:00
- [login ](#login )
2015-07-07 22:01:25 +00:00
- [logout ](#logout )
- [signup ](#signup )
- [whoami ](#whoami )
2015-04-16 13:34:40 +00:00
- Device
2015-07-07 22:01:25 +00:00
- [devices ](#devices )
2018-03-20 17:43:26 +00:00
- [device <uuid> ](#device-uuid- )
2016-09-25 23:51:32 +00:00
- [devices supported ](#devices-supported )
2018-03-20 17:43:26 +00:00
- [device register <application> ](#device-register-application- )
- [device rm <uuid> ](#device-rm-uuid- )
- [device identify <uuid> ](#device-identify-uuid- )
- [device reboot <uuid> ](#device-reboot-uuid- )
- [device shutdown <uuid> ](#device-shutdown-uuid- )
- [device public-url enable <uuid> ](#device-public-url-enable-uuid- )
- [device public-url disable <uuid> ](#device-public-url-disable-uuid- )
- [device public-url <uuid> ](#device-public-url-uuid- )
- [device public-url status <uuid> ](#device-public-url-status-uuid- )
- [device rename < uuid> [newName]](#device-rename-uuid-newname-)
- [device move <uuid> ](#device-move-uuid- )
2015-09-29 15:10:33 +00:00
- [device init ](#device-init )
2015-04-16 13:34:40 +00:00
- Environment Variables
2015-07-07 22:01:25 +00:00
- [envs ](#envs )
2018-03-20 17:43:26 +00:00
- [env rm <id> ](#env-rm-id- )
- [env add < key> [value]](#env-add-key-value-)
- [env rename <id> <value> ](#env-rename-id-value- )
2015-04-16 13:34:40 +00:00
2018-12-10 21:05:35 +00:00
- Tags
- [tags ](#tags )
- [tag set < tagKey> [value]](#tag-set-tagkey-value-)
- [tag rm <tagKey> ](#tag-rm-tagkey- )
2015-04-16 13:34:40 +00:00
- Help
2018-03-20 17:43:26 +00:00
- [help [command...]](#help-command-)
2015-04-16 13:34:40 +00:00
- Information
2015-07-07 22:01:25 +00:00
- [version ](#version )
2015-04-16 13:34:40 +00:00
- Keys
2015-07-07 22:01:25 +00:00
- [keys ](#keys )
2018-03-20 17:43:26 +00:00
- [key <id> ](#key-id- )
- [key rm <id> ](#key-rm-id- )
- [key add < name> [path]](#key-add-name-path-)
2015-04-16 13:34:40 +00:00
- Logs
2018-03-20 17:43:26 +00:00
- [logs <uuid> ](#logs-uuid- )
2015-04-16 13:34:40 +00:00
2016-03-28 13:25:40 +00:00
- Sync
2018-03-20 17:43:26 +00:00
- [sync [uuid]](#sync-uuid-)
2016-03-28 13:25:40 +00:00
2016-04-24 19:52:41 +00:00
- SSH
2018-03-20 17:43:26 +00:00
- [ssh [uuid]](#ssh-uuid-)
2016-04-24 19:52:41 +00:00
2015-04-16 13:34:40 +00:00
- Notes
2018-03-20 17:43:26 +00:00
- [note <|note> ](#note-note- )
2015-04-16 13:34:40 +00:00
2015-09-29 17:03:14 +00:00
- OS
2018-03-20 17:43:26 +00:00
- [os versions <type> ](#os-versions-type- )
- [os download <type> ](#os-download-type- )
- [os build-config <image> <device-type> ](#os-build-config-image-device-type- )
2018-10-15 17:03:21 +00:00
- [os configure <image> ](#os-configure-image- )
2018-03-20 17:43:26 +00:00
- [os initialize <image> ](#os-initialize-image- )
2015-09-29 17:03:14 +00:00
2015-11-10 16:53:34 +00:00
- Config
- [config read ](#config-read )
2018-03-20 17:43:26 +00:00
- [config write <key> <value> ](#config-write-key-value- )
- [config inject <file> ](#config-inject-file- )
2015-11-11 14:38:45 +00:00
- [config reconfigure ](#config-reconfigure )
2016-03-28 13:25:40 +00:00
- [config generate ](#config-generate )
2015-11-10 16:53:34 +00:00
2017-10-25 11:17:07 +00:00
- Preload
2018-03-20 17:43:26 +00:00
- [preload <image> ](#preload-image- )
2017-10-25 11:17:07 +00:00
2018-06-26 16:59:44 +00:00
- Push
2018-10-16 10:25:37 +00:00
- [push <applicationOrDevice> ](#push-applicationordevice- )
2018-06-26 16:59:44 +00:00
2015-11-16 02:08:02 +00:00
- Settings
- [settings ](#settings )
2015-09-01 17:01:47 +00:00
- Wizard
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
- [quickstart [name]](#quickstart-name-)
2015-04-16 13:34:40 +00:00
2017-04-11 13:25:54 +00:00
- Local
2018-03-20 17:43:26 +00:00
- [local configure <target> ](#local-configure-target- )
- [local flash <image> ](#local-flash-image- )
- [local logs [deviceIp]](#local-logs-deviceip-)
2017-04-11 13:25:54 +00:00
- [local scan ](#local-scan )
2018-03-20 17:43:26 +00:00
- [local ssh [deviceIp]](#local-ssh-deviceip-)
- [local push [deviceIp]](#local-push-deviceip-)
- [local stop [deviceIp]](#local-stop-deviceip-)
2017-04-11 13:25:54 +00:00
2017-04-26 12:34:40 +00:00
- Deploy
2018-03-20 17:43:26 +00:00
- [build [source]](#build-source-)
- [deploy < appName> [image]](#deploy-appname-image-)
2017-04-26 12:34:40 +00:00
2018-11-14 22:26:14 +00:00
- Platform
- [join [deviceIp]](#join-deviceip-)
- [leave [deviceIp]](#leave-deviceip-)
2017-06-14 21:23:39 +00:00
- Utilities
- [util available-drives ](#util-available-drives )
2018-04-04 12:42:57 +00:00
# Api keys
## api-key generate <name>
This command generates a new API key for the current user, with the given
name. The key will be logged to the console.
2018-10-19 14:38:50 +00:00
This key can be used to log into the CLI using 'balena login --token < key > ',
2018-04-04 12:42:57 +00:00
or to authenticate requests to the API with an 'Authorization: Bearer < key > ' header.
Examples:
2018-10-19 14:38:50 +00:00
$ balena api-key generate "Jenkins Key"
2018-04-04 12:42:57 +00:00
2015-04-16 13:34:40 +00:00
# Application
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## app create <name>
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Use this command to create a new balena application.
2015-04-16 13:34:40 +00:00
2017-05-12 10:01:37 +00:00
You can specify the application device type with the `--type` option.
2015-04-16 13:34:40 +00:00
Otherwise, an interactive dropdown will be shown for you to select from.
You can see a list of supported device types with
2018-10-19 14:38:50 +00:00
$ balena devices supported
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena app create MyApp
$ balena app create MyApp --type raspberry-pi
2015-04-16 13:34:40 +00:00
### Options
2017-05-12 10:01:37 +00:00
#### --type, -t <type>
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
application device type (Check available types with `balena devices supported` )
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## apps
2015-04-16 13:34:40 +00:00
Use this command to list all your applications.
Notice this command only shows the most important bits of information for each app.
2018-10-19 14:38:50 +00:00
If you want detailed information, use balena app < name > instead.
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena apps
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## app <name>
2015-04-16 13:34:40 +00:00
Use this command to show detailed information for a single application.
Examples:
2018-10-19 14:38:50 +00:00
$ balena app MyApp
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## app restart <name>
2015-04-16 13:34:40 +00:00
Use this command to restart all devices that belongs to a certain application.
Examples:
2018-10-19 14:38:50 +00:00
$ balena app restart MyApp
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## app rm <name>
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Use this command to remove a balena application.
2015-04-16 13:34:40 +00:00
Notice this command asks for confirmation interactively.
You can avoid this by passing the `--yes` boolean option.
Examples:
2018-10-19 14:38:50 +00:00
$ balena app rm MyApp
$ balena app rm MyApp --yes
2015-04-16 13:34:40 +00:00
### Options
#### --yes, -y
confirm non interactively
2015-11-11 12:45:38 +00:00
# Authentication
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## login
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Use this command to login to your balena account.
2015-06-02 16:32:35 +00:00
2016-01-12 13:07:15 +00:00
This command will prompt you to login using the following login types:
- Web authorization: open your web browser and prompt you to authorize the CLI
2015-12-03 14:22:22 +00:00
from the dashboard.
2016-01-12 13:07:15 +00:00
- Credentials: using email/password and 2FA.
2015-12-03 14:22:22 +00:00
2018-11-07 15:16:13 +00:00
- Token: using a session token or API key from the preferences page.
2015-12-12 04:09:31 +00:00
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena login
$ balena login --web
$ balena login --token "..."
$ balena login --credentials
$ balena login --credentials --email johndoe@gmail.com --password secret
2015-12-03 14:22:22 +00:00
### Options
#### --token, -t <token>
2018-11-07 15:16:13 +00:00
session token or API key
2015-04-16 13:34:40 +00:00
2016-01-12 13:07:15 +00:00
#### --web, -w
web-based login
2015-12-12 04:09:31 +00:00
#### --credentials, -c
credential-based login
2017-12-21 17:40:13 +00:00
#### --email, -e, -u <email>
2015-12-12 04:09:31 +00:00
email
#### --password, -p <password>
password
2018-03-20 17:43:26 +00:00
## logout
2015-04-16 13:34:40 +00:00
2018-12-28 13:40:18 +00:00
Use this command to logout from your balena account.
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena logout
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## signup
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Use this command to signup for a balena account.
2015-04-16 13:34:40 +00:00
If signup is successful, you'll be logged in to your new user automatically.
Examples:
2018-10-19 14:38:50 +00:00
$ balena signup
2017-03-27 09:29:40 +00:00
Email: johndoe@acme.com
2015-04-16 13:34:40 +00:00
Password: ** *********
2018-10-19 14:38:50 +00:00
$ balena whoami
2015-04-16 13:34:40 +00:00
johndoe
2018-03-20 17:43:26 +00:00
## whoami
2015-04-27 14:51:26 +00:00
2015-09-01 17:01:47 +00:00
Use this command to find out the current logged in username and email address.
2015-04-27 14:51:26 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena whoami
2015-04-27 14:51:26 +00:00
2015-04-16 13:34:40 +00:00
# Device
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## devices
2015-04-16 13:34:40 +00:00
2015-04-27 15:20:53 +00:00
Use this command to list all devices that belong to you.
You can filter the devices by application by using the `--application` option.
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena devices
$ balena devices --application MyApp
$ balena devices --app MyApp
$ balena devices -a MyApp
2015-04-16 13:34:40 +00:00
### Options
2017-12-21 17:40:13 +00:00
#### --application, -a, --app <application>
2015-04-16 13:34:40 +00:00
application name
2018-03-20 17:43:26 +00:00
## device <uuid>
2015-04-16 13:34:40 +00:00
Use this command to show information about a single device.
Examples:
2018-10-19 14:38:50 +00:00
$ balena device 7cf02a6
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## devices supported
2016-09-25 23:51:32 +00:00
Use this command to get the list of all supported devices
Examples:
2018-10-19 14:38:50 +00:00
$ balena devices supported
2016-09-25 23:51:32 +00:00
2018-03-20 17:43:26 +00:00
## device register <application>
2015-09-29 18:33:31 +00:00
Use this command to register a device to an application.
Examples:
2018-10-19 14:38:50 +00:00
$ balena device register MyApp
$ balena device register MyApp --uuid < uuid >
2015-09-29 18:33:31 +00:00
2015-10-19 18:16:47 +00:00
### Options
#### --uuid, -u <uuid>
custom uuid
2018-03-20 17:43:26 +00:00
## device rm <uuid>
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Use this command to remove a device from balena.
2015-04-16 13:34:40 +00:00
Notice this command asks for confirmation interactively.
You can avoid this by passing the `--yes` boolean option.
Examples:
2018-10-19 14:38:50 +00:00
$ balena device rm 7cf02a6
$ balena device rm 7cf02a6 --yes
2015-04-16 13:34:40 +00:00
### Options
#### --yes, -y
confirm non interactively
2018-03-20 17:43:26 +00:00
## device identify <uuid>
2015-04-16 13:34:40 +00:00
Use this command to identify a device.
In the Raspberry Pi, the ACT led is blinked several times.
Examples:
2018-10-19 14:38:50 +00:00
$ balena device identify 23c73a1
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## device reboot <uuid>
2016-03-04 13:38:11 +00:00
Use this command to remotely reboot a device
Examples:
2018-10-19 14:38:50 +00:00
$ balena device reboot 23c73a1
2016-03-04 13:38:11 +00:00
2016-10-26 14:46:20 +00:00
### Options
2017-01-18 15:57:52 +00:00
#### --force, -f
2016-10-26 14:46:20 +00:00
force action if the update lock is set
2018-03-20 17:43:26 +00:00
## device shutdown <uuid>
2016-10-26 14:46:20 +00:00
Use this command to remotely shutdown a device
Examples:
2018-10-19 14:38:50 +00:00
$ balena device shutdown 23c73a1
2016-10-26 14:46:20 +00:00
### Options
2017-01-18 15:57:52 +00:00
#### --force, -f
2016-10-26 14:46:20 +00:00
force action if the update lock is set
2018-03-20 17:43:26 +00:00
## device public-url enable <uuid>
2016-09-25 23:51:32 +00:00
Use this command to enable public URL for a device
Examples:
2018-10-19 14:38:50 +00:00
$ balena device public-url enable 23c73a1
2016-09-25 23:51:32 +00:00
2018-03-20 17:43:26 +00:00
## device public-url disable <uuid>
2016-09-25 23:51:32 +00:00
Use this command to disable public URL for a device
Examples:
2018-10-19 14:38:50 +00:00
$ balena device public-url disable 23c73a1
2016-09-25 23:51:32 +00:00
2018-03-20 17:43:26 +00:00
## device public-url <uuid>
2016-09-25 23:51:32 +00:00
Use this command to get the public URL of a device
Examples:
2018-10-19 14:38:50 +00:00
$ balena device public-url 23c73a1
2016-09-25 23:51:32 +00:00
2018-03-20 17:43:26 +00:00
## device public-url status <uuid>
2016-09-25 23:51:32 +00:00
Use this command to determine if public URL is enabled for a device
Examples:
2018-10-19 14:38:50 +00:00
$ balena device public-url status 23c73a1
2016-09-25 23:51:32 +00:00
2018-03-20 17:43:26 +00:00
## device rename <uuid> [newName]
2015-04-16 13:34:40 +00:00
Use this command to rename a device.
If you omit the name, you'll get asked for it interactively.
Examples:
2018-10-19 14:38:50 +00:00
$ balena device rename 7cf02a6
$ balena device rename 7cf02a6 MyPi
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## device move <uuid>
2015-11-11 19:00:02 +00:00
Use this command to move a device to another application you own.
If you omit the application, you'll get asked for it interactively.
Examples:
2018-10-19 14:38:50 +00:00
$ balena device move 7cf02a6
$ balena device move 7cf02a6 --application MyNewApp
2015-11-11 19:00:02 +00:00
### Options
2017-12-21 17:40:13 +00:00
#### --application, -a, --app <application>
2015-11-11 19:00:02 +00:00
application name
2018-03-20 17:43:26 +00:00
## device init
2015-04-16 13:34:40 +00:00
Use this command to download the OS image of a certain application and write it to an SD Card.
2015-09-29 15:10:33 +00:00
Notice this command may ask for confirmation interactively.
2015-04-16 13:34:40 +00:00
You can avoid this by passing the `--yes` boolean option.
Examples:
2018-10-19 14:38:50 +00:00
$ balena device init
$ balena device init --application MyApp
2015-04-16 13:34:40 +00:00
### Options
2017-12-21 17:40:13 +00:00
#### --application, -a, --app <application>
2015-04-16 13:34:40 +00:00
application name
2015-09-29 15:10:33 +00:00
#### --yes, -y
2015-04-16 13:34:40 +00:00
2015-09-29 15:10:33 +00:00
confirm non interactively
2015-04-16 13:34:40 +00:00
2015-10-20 13:16:56 +00:00
#### --advanced, -v
2017-06-14 21:51:56 +00:00
show advanced configuration options
2015-10-20 13:16:56 +00:00
2017-06-12 10:21:12 +00:00
#### --os-version <os-version>
exact version number, or a valid semver range,
or 'latest' (includes pre-releases),
or 'default' (excludes pre-releases if at least one stable version is available),
or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available),
or 'menu' (will show the interactive menu)
#### --drive, -d <drive>
2018-10-19 14:38:50 +00:00
the drive to write the image to, like `/dev/sdb` or `/dev/mmcblk0` . Careful with this as you can erase your hard drive. Check `balena util available-drives` for available options.
2017-06-12 10:21:12 +00:00
#### --config <config>
2018-10-19 14:38:50 +00:00
path to the config JSON file, see `balena os build-config`
2017-06-12 10:21:12 +00:00
2015-04-16 13:34:40 +00:00
# Environment Variables
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## envs
2015-04-16 13:34:40 +00:00
2015-07-07 22:01:25 +00:00
Use this command to list all environment variables for
a particular application or device.
2015-04-16 13:34:40 +00:00
2018-10-25 18:03:12 +00:00
This command lists all application/device environment variables.
2015-04-16 13:34:40 +00:00
2018-10-25 18:03:12 +00:00
If you want to see config variables, used to configure
balena features, use the --config option.
At the moment the CLI does not support per-service variables,
so the following commands will only show service-wide
environment variables.
2018-05-31 10:43:11 +00:00
2015-04-16 13:34:40 +00:00
Example:
2018-10-19 14:38:50 +00:00
$ balena envs --application MyApp
2018-10-25 18:03:12 +00:00
$ balena envs --application MyApp --config
2018-10-19 14:38:50 +00:00
$ balena envs --device 7cf02a6
2015-04-16 13:34:40 +00:00
### Options
2017-12-21 17:40:13 +00:00
#### --application, -a, --app <application>
2015-04-16 13:34:40 +00:00
application name
2015-07-07 22:01:25 +00:00
#### --device, -d <device>
2016-02-27 02:38:16 +00:00
device uuid
2015-07-07 22:01:25 +00:00
2018-10-25 18:03:12 +00:00
#### --config, -c, -v, --verbose
2015-04-16 13:34:40 +00:00
2018-10-25 18:03:12 +00:00
show config variables
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## env rm <id>
2015-04-16 13:34:40 +00:00
Use this command to remove an environment variable from an application.
Notice this command asks for confirmation interactively.
You can avoid this by passing the `--yes` boolean option.
2015-07-07 22:01:25 +00:00
If you want to eliminate a device environment variable, pass the `--device` boolean option.
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena env rm 215
$ balena env rm 215 --yes
$ balena env rm 215 --device
2015-04-16 13:34:40 +00:00
### Options
#### --yes, -y
confirm non interactively
2015-07-07 22:01:25 +00:00
#### --device, -d
2016-02-27 02:38:16 +00:00
device
2015-07-07 22:01:25 +00:00
2018-03-20 17:43:26 +00:00
## env add <key> [value]
2015-04-16 13:34:40 +00:00
2018-10-25 18:03:12 +00:00
Use this command to add an enviroment or config variable to an application.
2015-04-16 13:34:40 +00:00
2018-05-31 10:43:11 +00:00
At the moment the CLI doesn't fully support multi-container applications,
2018-10-25 18:03:12 +00:00
so the following commands will set service-wide environment variables.
2018-05-31 10:43:11 +00:00
2015-04-16 13:34:40 +00:00
If value is omitted, the tool will attempt to use the variable's value
as defined in your host machine.
2015-07-07 22:01:25 +00:00
Use the `--device` option if you want to assign the environment variable
to a specific device.
2015-04-16 13:34:40 +00:00
If the value is grabbed from the environment, a warning message will be printed.
Use `--quiet` to remove it.
Examples:
2018-10-19 14:38:50 +00:00
$ balena env add EDITOR vim --application MyApp
$ balena env add TERM --application MyApp
$ balena env add EDITOR vim --device 7cf02a6
2015-04-16 13:34:40 +00:00
### Options
2017-12-21 17:40:13 +00:00
#### --application, -a, --app <application>
2015-04-16 13:34:40 +00:00
application name
2015-07-07 22:01:25 +00:00
#### --device, -d <device>
2016-02-27 02:38:16 +00:00
device uuid
2015-07-07 22:01:25 +00:00
2018-03-20 17:43:26 +00:00
## env rename <id> <value>
2015-04-16 13:34:40 +00:00
2018-10-25 18:03:12 +00:00
Use this command to change the value of an enviroment variable.
2015-04-16 13:34:40 +00:00
2015-07-07 22:01:25 +00:00
Pass the `--device` boolean option if you want to rename a device environment variable.
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena env rename 376 emacs
$ balena env rename 376 emacs --device
2015-07-07 22:01:25 +00:00
### Options
#### --device, -d
2016-02-27 02:38:16 +00:00
device
2015-04-16 13:34:40 +00:00
2018-12-10 21:05:35 +00:00
# Tags
## tags
Use this command to list all tags for
a particular application, device or release.
This command lists all application/device/release tags.
Example:
$ balena tags --application MyApp
$ balena tags --device 7cf02a6
$ balena tags --release 1234
### Options
#### --application, -a, --app <application>
application name
#### --device, -d <device>
device uuid
#### --release, -r <release>
release id
## tag set <tagKey> [value]
Use this command to set a tag to an application, device or release.
You can optionally provide a value to be associated with the created
tag, as an extra argument after the tag key. When the value isn't
provided, a tag with an empty value is created.
Examples:
$ balena tag set mySimpleTag --application MyApp
$ balena tag set myCompositeTag myTagValue --application MyApp
$ balena tag set myCompositeTag myTagValue --device 7cf02a6
$ balena tag set myCompositeTag myTagValue --release 1234
$ balena tag set myCompositeTag "my tag value with whitespaces" --release 1234
### Options
#### --application, -a, --app <application>
application name
#### --device, -d <device>
device uuid
#### --release, -r <release>
release id
## tag rm <tagKey>
Use this command to remove a tag from an application, device or release.
Examples:
$ balena tag rm myTagKey --application MyApp
$ balena tag rm myTagKey --device 7cf02a6
$ balena tag rm myTagKey --release 1234
### Options
#### --application, -a, --app <application>
application name
#### --device, -d <device>
device uuid
#### --release, -r <release>
release id
2015-04-16 13:34:40 +00:00
# Help
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## help [command...]
2015-04-16 13:34:40 +00:00
Get detailed help for an specific command.
Examples:
2018-10-19 14:38:50 +00:00
$ balena help apps
$ balena help os download
2015-04-16 13:34:40 +00:00
2015-10-15 12:48:34 +00:00
### Options
#### --verbose, -v
show additional commands
2015-04-16 13:34:40 +00:00
# Information
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## version
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Display the balena CLI version.
2015-04-16 13:34:40 +00:00
# Keys
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## keys
2015-04-16 13:34:40 +00:00
Use this command to list all your SSH keys.
Examples:
2018-10-19 14:38:50 +00:00
$ balena keys
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## key <id>
2015-04-16 13:34:40 +00:00
Use this command to show information about a single SSH key.
Examples:
2018-10-19 14:38:50 +00:00
$ balena key 17
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## key rm <id>
2015-04-16 13:34:40 +00:00
2018-10-19 14:38:50 +00:00
Use this command to remove a SSH key from balena.
2015-04-16 13:34:40 +00:00
Notice this command asks for confirmation interactively.
You can avoid this by passing the `--yes` boolean option.
Examples:
2018-10-19 14:38:50 +00:00
$ balena key rm 17
$ balena key rm 17 --yes
2015-04-16 13:34:40 +00:00
### Options
#### --yes, -y
confirm non interactively
2018-03-20 17:43:26 +00:00
## key add <name> [path]
2015-04-16 13:34:40 +00:00
Use this command to associate a new SSH key with your account.
If `path` is omitted, the command will attempt
to read the SSH key from stdin.
Examples:
2018-10-19 14:38:50 +00:00
$ balena key add Main ~/.ssh/id_rsa.pub
$ cat ~/.ssh/id_rsa.pub | balena key add Main
2015-04-16 13:34:40 +00:00
# Logs
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## logs <uuid>
2015-04-16 13:34:40 +00:00
Use this command to show logs for a specific device.
By default, the command prints all log messages and exit.
To continuously stream output, and see new logs in real time, use the `--tail` option.
Examples:
2018-10-19 14:38:50 +00:00
$ balena logs 23c73a1
$ balena logs 23c73a1
2015-04-16 13:34:40 +00:00
### Options
#### --tail, -t
continuously stream output
2016-03-28 13:25:40 +00:00
# Sync
2018-03-20 17:43:26 +00:00
## sync [uuid]
2016-03-28 13:25:40 +00:00
2018-10-19 14:38:50 +00:00
Warning: 'balena sync' requires an openssh-compatible client and 'rsync' to
2017-01-18 15:57:52 +00:00
be correctly installed in your shell environment. For more information (including
2018-10-19 14:38:50 +00:00
Windows support) please check the README here: https://github.com/balena-io/balena-cli
2016-05-19 14:10:45 +00:00
2016-03-28 13:25:40 +00:00
Use this command to sync your local changes to a certain device on the fly.
2018-10-19 14:38:50 +00:00
After every 'balena sync' the updated settings will be saved in
'< source > /.balena-sync.yml' and will be used in later invocations. You can
also change any option by editing '.balena-sync.yml' directly.
2016-04-25 12:32:58 +00:00
2018-10-19 14:38:50 +00:00
Here is an example '.balena-sync.yml' :
2016-03-28 13:25:40 +00:00
2018-10-19 14:38:50 +00:00
$ cat $PWD/.balena-sync.yml
2016-07-21 16:35:44 +00:00
uuid: 7cf02a6
destination: '/usr/src/app'
2016-03-28 13:25:40 +00:00
before: 'echo Hello'
2016-07-21 16:35:44 +00:00
after: 'echo Done'
2016-03-28 13:25:40 +00:00
ignore:
- .git
- node_modules/
2018-10-19 14:38:50 +00:00
Command line options have precedence over the ones saved in '.balena-sync.yml'.
2016-07-21 16:35:44 +00:00
If '.gitignore' is found in the source directory then all explicitly listed files will be
excluded from the syncing process. You can choose to change this default behavior with the
'--skip-gitignore' option.
2016-03-28 13:25:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena sync 7cf02a6 --source . --destination /usr/src/app
$ balena sync 7cf02a6 -s /home/user/myBalenaProject -d /usr/src/app --before 'echo Hello' --after 'echo Done'
$ balena sync --ignore lib/
$ balena sync --verbose false
$ balena sync
2016-03-28 13:25:40 +00:00
### Options
#### --source, -s <path>
2016-07-21 16:35:44 +00:00
local directory path to synchronize to device
#### --destination, -d <path>
destination path on device
2016-03-28 13:25:40 +00:00
#### --ignore, -i <paths>
comma delimited paths to ignore when syncing
2016-07-21 16:35:44 +00:00
#### --skip-gitignore
do not parse excluded/included files from .gitignore
2017-03-22 09:46:06 +00:00
#### --skip-restart
do not restart container after syncing
2016-03-28 13:25:40 +00:00
#### --before, -b <command>
execute a command before syncing
2016-07-21 16:35:44 +00:00
#### --after, -a <command>
2016-03-28 13:25:40 +00:00
2016-07-21 16:35:44 +00:00
execute a command after syncing
2016-03-28 13:25:40 +00:00
#### --port, -t <port>
ssh port
2016-07-21 16:35:44 +00:00
#### --progress, -p
show progress
2016-06-22 20:19:31 +00:00
#### --verbose, -v
increase verbosity
2016-04-24 19:52:41 +00:00
# SSH
2018-03-20 17:43:26 +00:00
## ssh [uuid]
2016-05-19 14:10:45 +00:00
2018-10-19 14:38:50 +00:00
Warning: 'balena ssh' requires an openssh-compatible client to be correctly
2017-01-18 15:57:52 +00:00
installed in your shell environment. For more information (including Windows
2018-10-19 14:38:50 +00:00
support) please check the README here: https://github.com/balena-io/balena-cli
2016-04-24 19:52:41 +00:00
Use this command to get a shell into the running application container of
your device.
Examples:
2018-10-19 14:38:50 +00:00
$ balena ssh MyApp
$ balena ssh 7cf02a6
$ balena ssh 7cf02a6 --port 8080
$ balena ssh 7cf02a6 -v
$ balena ssh 7cf02a6 -s
2016-04-24 19:52:41 +00:00
### Options
2016-07-21 16:35:44 +00:00
#### --port, -p <port>
2016-04-24 19:52:41 +00:00
2016-05-19 14:10:45 +00:00
ssh gateway port
2016-04-24 19:52:41 +00:00
2016-06-22 13:46:18 +00:00
#### --verbose, -v
increase verbosity
2017-12-18 13:31:07 +00:00
#### --host, -s
2017-12-18 10:36:58 +00:00
2018-10-19 14:38:50 +00:00
access host OS (for devices with balenaOS >= 2.7.5)
2017-12-18 10:36:58 +00:00
2017-05-18 22:44:30 +00:00
#### --noproxy
2017-05-18 22:25:01 +00:00
don't use the proxy configuration for this connection. Only makes sense if you've configured proxy globally.
2015-04-16 13:34:40 +00:00
# Notes
2015-04-16 14:42:09 +00:00
2018-03-20 17:43:26 +00:00
## note <|note>
2015-04-16 13:34:40 +00:00
Use this command to set or update a device note.
If note command isn't passed, the tool attempts to read from `stdin` .
2018-10-19 14:38:50 +00:00
To view the notes, use $ balena device < uuid > .
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena note "My useful note" --device 7cf02a6
$ cat note.txt | balena note --device 7cf02a6
2015-04-16 13:34:40 +00:00
### Options
2017-12-21 17:40:13 +00:00
#### --device, -d, --dev <device>
2015-04-16 13:34:40 +00:00
2015-08-04 14:00:09 +00:00
device uuid
2015-04-16 13:34:40 +00:00
2015-09-29 17:03:14 +00:00
# OS
2018-03-20 17:43:26 +00:00
## os versions <type>
2017-06-12 10:21:12 +00:00
2018-10-19 14:38:50 +00:00
Use this command to show the available balenaOS versions for a certain device type.
Check available types with `balena devices supported`
2017-06-12 10:21:12 +00:00
Example:
2018-10-19 14:38:50 +00:00
$ balena os versions raspberrypi3
2017-06-12 10:21:12 +00:00
2018-03-20 17:43:26 +00:00
## os download <type>
2015-09-29 17:03:14 +00:00
Use this command to download an unconfigured os image for a certain device type.
2018-10-19 14:38:50 +00:00
Check available types with `balena devices supported`
2015-09-29 17:03:14 +00:00
2017-03-22 10:50:06 +00:00
If version is not specified the newest stable (non-pre-release) version of OS
is downloaded if available, or the newest version otherwise (if all existing
versions for the given device type are pre-release).
You can pass `--version menu` to pick the OS version from the interactive menu
of all available versions.
2015-09-29 17:03:14 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img
$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 1.24.1
$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version ^1.20.0
$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version latest
$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version default
$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu
2015-09-29 17:03:14 +00:00
### Options
#### --output, -o <output>
output path
2017-03-22 10:50:06 +00:00
#### --version <version>
exact version number, or a valid semver range,
or 'latest' (includes pre-releases),
or 'default' (excludes pre-releases if at least one stable version is available),
or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available),
or 'menu' (will show the interactive menu)
2018-03-20 17:43:26 +00:00
## os build-config <image> <device-type>
2017-06-12 10:21:12 +00:00
2018-10-19 14:38:50 +00:00
Use this command to prebuild the OS config once and skip the interactive part of `balena os configure` .
2017-06-12 10:21:12 +00:00
2017-11-16 18:11:17 +00:00
Example:
2017-06-12 10:21:12 +00:00
2018-10-19 14:38:50 +00:00
$ balena os build-config ../path/rpi3.img raspberrypi3 --output rpi3-config.json
$ balena os configure ../path/rpi3.img 7cf02a6 --config "$(cat rpi3-config.json)"
2017-06-12 10:21:12 +00:00
### Options
#### --advanced, -v
2017-06-14 21:51:56 +00:00
show advanced configuration options
2017-06-12 10:21:12 +00:00
#### --output, -o <output>
the path to the output JSON file
2018-10-15 17:03:21 +00:00
## os configure <image>
2015-09-29 17:36:29 +00:00
2017-11-16 18:13:20 +00:00
Use this command to configure a previously downloaded operating system image for
the specific device or for an application generally.
2015-09-29 17:36:29 +00:00
2018-11-05 08:18:18 +00:00
This command will try to automatically determine the operating system version in order
to correctly configure the image. It may fail to do so however, in which case you'll
have to call this command again with the exact version number of the targeted image.
2018-07-11 18:56:13 +00:00
2018-10-19 14:38:50 +00:00
Note that device api keys are only supported on balenaOS 2.0.3+.
2017-11-16 18:13:20 +00:00
2018-07-11 18:56:13 +00:00
This command still supports the *deprecated* format where the UUID and optionally device key
2017-11-16 18:13:20 +00:00
are passed directly on the command line, but the recommended way is to pass either an --app or
--device argument. The deprecated format will be remove in a future release.
2017-10-13 18:29:47 +00:00
2018-12-07 15:44:18 +00:00
In case that you want to configure an image for an application with mixed device types,
you can pass the --device-type argument along with --app to specify the target device type.
2015-09-29 17:36:29 +00:00
Examples:
2018-12-07 15:44:18 +00:00
$ balena os configure ../path/rpi3.img --device 7cf02a6
$ balena os configure ../path/rpi3.img --device 7cf02a6 --device-api-key < existingDeviceKey >
$ balena os configure ../path/rpi3.img --app MyApp
$ balena os configure ../path/rpi3.img --app MyApp --version 2.12.7
$ balena os configure ../path/rpi3.img --app MyFinApp --device-type raspberrypi3
2015-09-29 17:36:29 +00:00
2015-10-19 17:38:09 +00:00
### Options
#### --advanced, -v
2017-06-14 21:51:56 +00:00
show advanced configuration options
2015-10-19 17:38:09 +00:00
2017-12-21 17:40:13 +00:00
#### --application, -a, --app <application>
2017-11-16 18:13:20 +00:00
application name
#### --device, -d <device>
device uuid
#### --deviceApiKey, -k <device-api-key>
2018-10-19 14:38:50 +00:00
custom device key - note that this is only supported on balenaOS 2.0.3+
2017-11-16 18:13:20 +00:00
2018-12-07 15:44:18 +00:00
#### --deviceType <device-type>
device type slug
2018-07-11 18:56:13 +00:00
#### --version <version>
2018-10-19 14:38:50 +00:00
a balenaOS version
2018-07-11 18:56:13 +00:00
2017-06-12 10:21:12 +00:00
#### --config <config>
2018-10-19 14:38:50 +00:00
path to the config JSON file, see `balena os build-config`
2017-06-12 10:21:12 +00:00
2018-03-20 17:43:26 +00:00
## os initialize <image>
2015-09-29 18:52:34 +00:00
2017-03-24 09:48:14 +00:00
Use this command to initialize a device with previously configured operating system image.
Note: Initializing the device may ask for administrative permissions
because we need to access the raw devices directly.
2015-09-29 18:52:34 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena os initialize ../path/rpi.img --type 'raspberry-pi'
2015-10-15 12:48:34 +00:00
### Options
#### --yes, -y
confirm non interactively
2017-05-12 10:01:37 +00:00
#### --type, -t <type>
2015-10-15 12:48:34 +00:00
2018-10-19 14:38:50 +00:00
device type (Check available types with `balena devices supported` )
2015-09-29 18:52:34 +00:00
2015-10-20 13:17:48 +00:00
#### --drive, -d <drive>
2018-10-19 14:38:50 +00:00
the drive to write the image to, like `/dev/sdb` or `/dev/mmcblk0` . Careful with this as you can erase your hard drive. Check `balena util available-drives` for available options.
2015-10-20 13:17:48 +00:00
2015-11-10 16:53:34 +00:00
# Config
2018-03-20 17:43:26 +00:00
## config read
2015-11-10 16:53:34 +00:00
2016-06-22 13:46:18 +00:00
Use this command to read the config.json file from the mounted filesystem (e.g. SD card) of a provisioned device"
2015-11-10 16:53:34 +00:00
2015-11-10 18:27:01 +00:00
Examples:
2015-11-10 16:53:34 +00:00
2018-10-19 14:38:50 +00:00
$ balena config read --type raspberry-pi
$ balena config read --type raspberry-pi --drive /dev/disk2
2015-11-10 16:53:34 +00:00
### Options
2017-05-12 10:01:37 +00:00
#### --type, -t <type>
2015-11-10 16:53:34 +00:00
2018-10-19 14:38:50 +00:00
device type (Check available types with `balena devices supported` )
2015-11-10 16:53:34 +00:00
#### --drive, -d <drive>
drive
2018-03-20 17:43:26 +00:00
## config write <key> <value>
2015-11-10 18:27:01 +00:00
2016-06-22 13:46:18 +00:00
Use this command to write the config.json file to the mounted filesystem (e.g. SD card) of a provisioned device
2015-11-10 18:27:01 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena config write --type raspberry-pi username johndoe
$ balena config write --type raspberry-pi --drive /dev/disk2 username johndoe
$ balena config write --type raspberry-pi files.network/settings "..."
2015-11-10 18:27:01 +00:00
### Options
2017-05-12 10:01:37 +00:00
#### --type, -t <type>
2015-11-10 18:27:01 +00:00
2018-10-19 14:38:50 +00:00
device type (Check available types with `balena devices supported` )
2015-11-10 18:27:01 +00:00
#### --drive, -d <drive>
drive
2018-03-20 17:43:26 +00:00
## config inject <file>
2016-03-17 20:07:19 +00:00
2018-01-26 14:43:00 +00:00
Use this command to inject a config.json file to the mounted filesystem
2018-10-19 14:38:50 +00:00
(e.g. SD card or mounted balenaOS image) of a provisioned device"
2016-03-17 20:07:19 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena config inject my/config.json --type raspberry-pi
$ balena config inject my/config.json --type raspberry-pi --drive /dev/disk2
2016-03-17 20:07:19 +00:00
### Options
2017-05-12 10:01:37 +00:00
#### --type, -t <type>
2016-03-17 20:07:19 +00:00
2018-10-19 14:38:50 +00:00
device type (Check available types with `balena devices supported` )
2016-03-17 20:07:19 +00:00
#### --drive, -d <drive>
drive
2018-03-20 17:43:26 +00:00
## config reconfigure
2015-11-11 14:38:45 +00:00
Use this command to reconfigure a provisioned device
Examples:
2018-10-19 14:38:50 +00:00
$ balena config reconfigure --type raspberry-pi
$ balena config reconfigure --type raspberry-pi --advanced
$ balena config reconfigure --type raspberry-pi --drive /dev/disk2
2015-11-11 14:38:45 +00:00
### Options
2017-05-12 10:01:37 +00:00
#### --type, -t <type>
2015-11-11 14:38:45 +00:00
2018-10-19 14:38:50 +00:00
device type (Check available types with `balena devices supported` )
2015-11-11 14:38:45 +00:00
#### --drive, -d <drive>
drive
#### --advanced, -v
show advanced commands
2018-03-20 17:43:26 +00:00
## config generate
2016-02-27 02:37:15 +00:00
2017-11-14 13:14:53 +00:00
Use this command to generate a config.json for a device or application.
2018-10-15 17:03:21 +00:00
Calling this command with the exact version number of the targeted image is required.
2018-07-11 18:56:13 +00:00
2017-11-14 13:14:53 +00:00
This is interactive by default, but you can do this automatically without interactivity
by specifying an option for each question on the command line, if you know the questions
that will be asked for the relevant device type.
2016-02-27 02:37:15 +00:00
2018-12-07 15:44:18 +00:00
In case that you want to configure an image for an application with mixed device types,
you can pass the --device-type argument along with --app to specify the target device type.
2016-02-27 02:37:15 +00:00
Examples:
2018-11-23 13:33:41 +00:00
$ balena config generate --device 7cf02a6 --version 2.12.7
$ balena config generate --device 7cf02a6 --version 2.12.7 --generate-device-api-key
$ balena config generate --device 7cf02a6 --version 2.12.7 --device-api-key < existingDeviceKey >
$ balena config generate --device 7cf02a6 --version 2.12.7 --output config.json
$ balena config generate --app MyApp --version 2.12.7
2018-12-07 15:44:18 +00:00
$ balena config generate --app MyApp --version 2.12.7 --device-type fincm3
2018-11-23 13:33:41 +00:00
$ balena config generate --app MyApp --version 2.12.7 --output config.json
$ balena config generate --app MyApp --version 2.12.7 --network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 1
2016-02-27 02:37:15 +00:00
### Options
2018-07-11 18:56:13 +00:00
#### --version <version>
2018-10-19 14:38:50 +00:00
a balenaOS version
2018-07-11 18:56:13 +00:00
2017-12-21 17:40:13 +00:00
#### --application, -a, --app <application>
2016-03-28 13:25:40 +00:00
application name
#### --device, -d <device>
device uuid
2017-04-19 03:21:59 +00:00
#### --deviceApiKey, -k <device-api-key>
2018-10-19 14:38:50 +00:00
custom device key - note that this is only supported on balenaOS 2.0.3+
2017-04-19 03:21:59 +00:00
2018-12-07 15:44:18 +00:00
#### --deviceType <device-type>
device type slug
2018-07-10 17:45:48 +00:00
#### --generate-device-api-key
generate a fresh device key for the device
2016-02-27 02:37:15 +00:00
#### --output, -o <output>
output
2017-11-14 13:14:53 +00:00
#### --network <network>
the network type to use: ethernet or wifi
#### --wifiSsid <wifiSsid>
the wifi ssid to use (used only if --network is set to wifi)
#### --wifiKey <wifiKey>
the wifi key to use (used only if --network is set to wifi)
#### --appUpdatePollInterval <appUpdatePollInterval>
how frequently (in minutes) to poll for application updates
2017-10-25 11:17:07 +00:00
# Preload
2018-03-20 17:43:26 +00:00
## preload <image>
2017-10-25 11:17:07 +00:00
2018-10-19 14:38:50 +00:00
Warning: "balena preload" requires Docker to be correctly installed in
2017-10-25 11:17:07 +00:00
your shell environment. For more information (including Windows support)
2018-10-19 14:38:50 +00:00
please check the README here: https://github.com/balena-io/balena-cli .
2017-10-25 11:17:07 +00:00
Use this command to preload an application to a local disk image (or
2018-10-19 14:38:50 +00:00
Edison zip archive) with a built release from balena.
2017-10-25 11:17:07 +00:00
Examples:
2018-10-03 13:27:53 +00:00
2018-10-19 14:38:50 +00:00
$ balena preload balena.img --app 1234 --commit e1f2592fc6ee949e68756d4f4a48e49bff8d72a0 --splash-image image.png
$ balena preload balena.img
2017-10-25 11:17:07 +00:00
### Options
#### --app, -a <appId>
id of the application to preload
#### --commit, -c <hash>
2018-01-30 17:31:49 +00:00
the commit hash for a specific application release to preload, use "latest" to specify the latest release
2017-10-25 11:17:07 +00:00
(ignored if no appId is given)
#### --splash-image, -s <splashImage.png>
path to a png image to replace the splash screen
2018-08-20 16:19:10 +00:00
#### --dont-check-arch
2017-10-25 11:17:07 +00:00
2018-08-20 16:19:10 +00:00
Disables check for matching architecture in image and application
2017-10-25 11:17:07 +00:00
2018-05-30 13:33:05 +00:00
#### --pin-device-to-release, -p
Pin the preloaded device to the preloaded release on provision
2017-10-25 11:17:07 +00:00
#### --docker, -P <docker>
Path to a local docker socket
#### --dockerHost, -h <dockerHost>
The address of the host containing the docker daemon
#### --dockerPort, -p <dockerPort>
The port on which the host docker daemon is listening
#### --ca <ca>
Docker host TLS certificate authority file
#### --cert <cert>
Docker host TLS certificate file
#### --key <key>
Docker host TLS key file
2018-06-26 16:59:44 +00:00
# Push
2018-10-16 10:25:37 +00:00
## push <applicationOrDevice>
2018-06-26 16:59:44 +00:00
2018-11-07 18:15:05 +00:00
This command can be used to start a build on the remote balena cloud builders,
or a local mode balena device.
2018-10-16 10:25:37 +00:00
2018-10-19 14:38:50 +00:00
When building on the balena cloud the given source directory will be sent to the
balena builder, and the build will proceed. This can be used as a drop-in
2018-06-26 16:59:44 +00:00
replacement for git push to deploy.
2018-11-07 18:15:05 +00:00
When building on a local mode device, the given source directory will be built
on the device, and the resulting containers will be run on the device. Logs will
be streamed back from the device as part of the same invocation.
The --registry-secrets option specifies a JSON or YAML file containing private
Docker registry usernames and passwords to be used when pulling base images.
Sample registry-secrets YAML file:
'https://idx.docker.io/v1/':
username: mike
password: cze14
'myregistry.com:25000':
username: ann
password: hunter2
2018-10-16 10:25:37 +00:00
2018-06-26 16:59:44 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena push myApp
$ balena push myApp --source < source directory >
$ balena push myApp -s < source directory >
2018-06-26 16:59:44 +00:00
2018-10-19 14:38:50 +00:00
$ balena push 10.0.0.1
$ balena push 10.0.0.1 --source < source directory >
$ balena push 10.0.0.1 -s < source directory >
2018-10-16 10:25:37 +00:00
2018-06-26 16:59:44 +00:00
### Options
#### --source, -s <source>
2018-10-19 14:38:50 +00:00
The source that should be sent to the balena builder to be built (defaults to the current directory)
2018-06-26 16:59:44 +00:00
2018-06-21 13:29:25 +00:00
#### --emulated, -e
Force an emulated build to occur on the remote builder
#### --nocache, -c
Don't use cache when building this project
2018-11-07 18:15:05 +00:00
#### --registry-secrets, -R <secrets.yml|.json>
Path to a local YAML or JSON file containing Docker registry passwords used to pull base images
2015-11-16 02:08:02 +00:00
# Settings
2018-03-20 17:43:26 +00:00
## settings
2015-11-16 02:08:02 +00:00
Use this command to display detected settings
Examples:
2018-10-19 14:38:50 +00:00
$ balena settings
2015-11-16 02:08:02 +00:00
2015-09-01 17:01:47 +00:00
# Wizard
2015-04-16 13:34:40 +00:00
2018-03-20 17:43:26 +00:00
## quickstart [name]
2015-04-16 14:42:09 +00:00
2018-10-19 14:38:50 +00:00
Use this command to run a friendly wizard to get started with balena.
2015-04-16 13:34:40 +00:00
2015-09-01 17:01:47 +00:00
The wizard will guide you through:
2015-04-16 13:34:40 +00:00
2015-09-01 17:01:47 +00:00
- Create an application.
2018-10-19 14:38:50 +00:00
- Initialise an SDCard with the balena operating system.
- Associate an existing project directory with your balena application.
2015-09-01 17:01:47 +00:00
- Push your project to your devices.
2015-04-16 13:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena quickstart
$ balena quickstart MyApp
2015-04-16 13:34:40 +00:00
2017-04-11 13:25:54 +00:00
# Local
2018-03-20 17:43:26 +00:00
## local configure <target>
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
Use this command to configure or reconfigure a balenaOS drive or image.
2017-04-11 13:25:54 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena local configure /dev/sdc
$ balena local configure path/to/image.img
2017-04-11 13:25:54 +00:00
2018-03-20 17:43:26 +00:00
## local flash <image>
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
Use this command to flash a balenaOS image to a drive.
2017-04-11 13:25:54 +00:00
Examples:
2019-01-17 00:10:17 +00:00
$ balena local flash path/to/balenaos.img[.zip|.gz|.bz2|.xz]
2018-10-19 14:38:50 +00:00
$ balena local flash path/to/balenaos.img --drive /dev/disk2
$ balena local flash path/to/balenaos.img --drive /dev/disk2 --yes
2017-04-11 13:25:54 +00:00
### Options
#### --yes, -y
confirm non-interactively
#### --drive, -d <drive>
drive
2018-03-20 17:43:26 +00:00
## local logs [deviceIp]
2017-04-11 13:25:54 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena local logs
$ balena local logs -f
$ balena local logs 192.168.1.10
$ balena local logs 192.168.1.10 -f
$ balena local logs 192.168.1.10 -f --app-name myapp
2017-04-11 13:25:54 +00:00
### Options
#### --follow, -f
follow log
#### --app-name, -a <name>
name of container to get logs from
2018-03-20 17:43:26 +00:00
## local scan
2017-04-11 13:25:54 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena local scan
$ balena local scan --timeout 120
$ balena local scan --verbose
2017-04-11 13:25:54 +00:00
### Options
#### --verbose, -v
Display full info
#### --timeout, -t <timeout>
Scan timeout in seconds
2018-03-20 17:43:26 +00:00
## local ssh [deviceIp]
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
Warning: 'balena local ssh' requires an openssh-compatible client to be correctly
2017-04-11 13:25:54 +00:00
installed in your shell environment. For more information (including Windows
2018-10-19 14:38:50 +00:00
support) please check the README here: https://github.com/balena-io/balena-cli
2017-04-11 13:25:54 +00:00
Use this command to get a shell into the running application container of
your device.
2018-10-19 14:38:50 +00:00
The '--host' option will get you a shell into the Host OS of the balenaOS device.
2017-04-11 13:25:54 +00:00
No option will return a list of containers to enter or you can explicitly select
one by passing its name to the --container option
Examples:
2018-10-19 14:38:50 +00:00
$ balena local ssh
$ balena local ssh --host
$ balena local ssh --container chaotic_water
$ balena local ssh --container chaotic_water --port 22222
$ balena local ssh --verbose
2017-04-11 13:25:54 +00:00
### Options
#### --verbose, -v
increase verbosity
#### --host, -s
get a shell into the host OS
#### --container, -c <container>
name of container to access
#### --port, -p <port>
ssh port number (default: 22222)
2018-03-20 17:43:26 +00:00
## local push [deviceIp]
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
Warning: 'balena local push' requires an openssh-compatible client and 'rsync' to
2017-04-11 13:25:54 +00:00
be correctly installed in your shell environment. For more information (including
2018-10-19 14:38:50 +00:00
Windows support) please check the README here: https://github.com/balena-io/balena-cli
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
Use this command to push your local changes to a container on a LAN-accessible balenaOS device on the fly.
2017-04-11 13:25:54 +00:00
If `Dockerfile` or any file in the 'build-triggers' list is changed,
a new container will be built and run on your device.
If not, changes will simply be synced with `rsync` into the application container.
2018-10-19 14:38:50 +00:00
After every 'balena local push' the updated settings will be saved in
'< source > /.balena-sync.yml' and will be used in later invocations. You can
also change any option by editing '.balena-sync.yml' directly.
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
Here is an example '.balena-sync.yml' :
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
$ cat $PWD/.balena-sync.yml
local_balenaos:
2018-07-31 19:46:07 +00:00
app-name: local-app
build-triggers:
2018-08-09 09:20:05 +00:00
- Dockerfile: file-hash-abcdefabcdefabcdefabcdefabcdefabcdef
- package.json: file-hash-abcdefabcdefabcdefabcdefabcdefabcdef
2018-07-31 19:46:07 +00:00
environment:
- MY_VARIABLE=123
2017-04-11 13:25:54 +00:00
2018-10-19 14:38:50 +00:00
Command line options have precedence over the ones saved in '.balena-sync.yml'.
2017-04-11 13:25:54 +00:00
If '.gitignore' is found in the source directory then all explicitly listed files will be
excluded when using rsync to update the container. You can choose to change this default behavior with the
'--skip-gitignore' option.
Examples:
2018-10-19 14:38:50 +00:00
$ balena local push
$ balena local push --app-name test-server --build-triggers package.json,requirements.txt
$ balena local push --force-build
$ balena local push --force-build --skip-logs
$ balena local push --ignore lib/
$ balena local push --verbose false
$ balena local push 192.168.2.10 --source . --destination /usr/src/app
$ balena local push 192.168.2.10 -s /home/user/balenaProject -d /usr/src/app --before 'echo Hello' --after 'echo Done'
2017-04-11 13:25:54 +00:00
### Options
#### --source, -s <path>
root of project directory to push
#### --destination, -d <path>
destination path on device container
#### --ignore, -i <paths>
comma delimited paths to ignore when syncing with 'rsync'
#### --skip-gitignore
do not parse excluded/included files from .gitignore
#### --before, -b <command>
execute a command before pushing
#### --after, -a <command>
execute a command after pushing
#### --progress, -p
show progress
#### --skip-logs
do not stream logs after push
#### --verbose, -v
increase verbosity
#### --app-name, -n <name>
application name - may contain lowercase characters, digits and one or more dashes. It may not start or end with a dash.
#### --build-triggers, -r <files>
comma delimited file list that will trigger a container rebuild if changed
#### --force-build, -f
force a container build and run
#### --env, -e <env>
environment variable (e.g. --env 'ENV=value'). Multiple --env parameters are supported.
2018-03-20 17:43:26 +00:00
## local stop [deviceIp]
2017-04-11 13:25:54 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena local stop
$ balena local stop --app-name myapp
$ balena local stop --all
$ balena local stop 192.168.1.10
$ balena local stop 192.168.1.10 --app-name myapp
2017-04-11 13:25:54 +00:00
### Options
#### --all
stop all containers
#### --app-name, -a <name>
name of container to stop
2017-04-26 12:34:40 +00:00
# Deploy
2018-03-20 17:43:26 +00:00
## build [source]
2017-04-26 12:34:40 +00:00
2017-12-11 22:37:56 +00:00
Use this command to build an image or a complete multicontainer project
with the provided docker daemon.
2017-04-26 12:34:40 +00:00
You must provide either an application or a device-type/architecture
2018-10-19 14:38:50 +00:00
pair to use the balena Dockerfile pre-processor
2017-04-26 12:34:40 +00:00
(e.g. Dockerfile.template -> Dockerfile).
2017-12-11 22:37:56 +00:00
This command will look into the given source directory (or the current working
directory if one isn't specified) for a compose file. If one is found, this
command will build each service defined in the compose file. If a compose file
isn't found, the command will look for a Dockerfile, and if yet that isn't found,
it will try to generate one.
2017-04-26 12:34:40 +00:00
Examples:
2018-10-19 14:38:50 +00:00
$ balena build
$ balena build ./source/
2018-12-03 13:10:54 +00:00
$ balena build --deviceType raspberrypi3 --arch armv7hf --emulated
2018-10-19 14:38:50 +00:00
$ balena build --application MyApp ./source/
$ balena build --docker '/var/run/docker.sock'
$ balena build --dockerHost my.docker.host --dockerPort 2376 --ca ca.pem --key key.pem --cert cert.pem
2017-04-26 12:34:40 +00:00
### Options
#### --arch, -A <arch>
The architecture to build for
2017-05-29 12:59:25 +00:00
#### --deviceType, -d <deviceType>
2017-04-26 12:34:40 +00:00
The type of device this build is for
#### --application, -a <application>
2018-10-19 14:38:50 +00:00
The target balena application this build is for
2017-04-26 12:34:40 +00:00
2017-12-11 22:37:56 +00:00
#### --projectName, -n <projectName>
Specify an alternate project name; default is the directory name
#### --emulated, -e
Run an emulated build using Qemu
#### --logs
Display full log output
2017-04-26 12:34:40 +00:00
#### --docker, -P <docker>
Path to a local docker socket
#### --dockerHost, -h <dockerHost>
The address of the host containing the docker daemon
#### --dockerPort, -p <dockerPort>
The port on which the host docker daemon is listening
#### --ca <ca>
Docker host TLS certificate authority file
#### --cert <cert>
Docker host TLS certificate file
#### --key <key>
Docker host TLS key file
#### --tag, -t <tag>
The alias to the generated image
2017-05-12 10:01:37 +00:00
#### --buildArg, -B <arg>
Set a build-time variable (eg. "-B 'ARG=value'"). Can be specified multiple times.
2017-04-26 12:34:40 +00:00
#### --nocache
Don't use docker layer caching when building
2017-06-23 15:20:16 +00:00
#### --squash
Squash newly built layers into a single new layer
2018-03-20 17:43:26 +00:00
## deploy <appName> [image]
2017-04-26 12:34:40 +00:00
2017-12-11 22:37:56 +00:00
Use this command to deploy an image or a complete multicontainer project
to an application, optionally building it first.
2017-04-26 12:34:40 +00:00
2017-10-09 17:10:50 +00:00
Usage: `deploy <appName> ([image] | --build [--source build-dir])`
2017-12-11 22:37:56 +00:00
Unless an image is specified, this command will look into the current directory
(or the one specified by --source) for a compose file. If one is found, this
command will deploy each service defined in the compose file, building it first
if an image for it doesn't exist. If a compose file isn't found, the command
will look for a Dockerfile, and if yet that isn't found, it will try to
generate one.
2017-10-09 17:10:50 +00:00
To deploy to an app on which you're a collaborator, use
2018-10-19 14:38:50 +00:00
`balena deploy <appOwnerUsername>/<appName>` .
2017-04-26 12:34:40 +00:00
2018-10-19 14:38:50 +00:00
Note: If building with this command, all options supported by `balena build`
2017-04-26 12:34:40 +00:00
are also supported with this command.
Examples:
2017-12-11 22:37:56 +00:00
2018-10-19 14:38:50 +00:00
$ balena deploy myApp
$ balena deploy myApp --build --source myBuildDir/
$ balena deploy myApp myApp/myImage
2017-04-26 12:34:40 +00:00
### Options
2017-12-11 22:37:56 +00:00
#### --source, -s <source>
2017-04-26 12:34:40 +00:00
2017-12-11 22:37:56 +00:00
Specify an alternate source directory; default is the working directory
2017-04-26 12:34:40 +00:00
2017-12-11 22:37:56 +00:00
#### --build, -b
2017-04-26 12:34:40 +00:00
2017-12-11 22:37:56 +00:00
Force a rebuild before deploy
2017-04-26 12:34:40 +00:00
2017-05-12 10:01:37 +00:00
#### --nologupload
Don't upload build logs to the dashboard with image (if building)
2017-12-11 22:37:56 +00:00
#### --projectName, -n <projectName>
Specify an alternate project name; default is the directory name
#### --emulated, -e
Run an emulated build using Qemu
#### --logs
Display full log output
2017-04-26 12:34:40 +00:00
#### --docker, -P <docker>
Path to a local docker socket
#### --dockerHost, -h <dockerHost>
The address of the host containing the docker daemon
#### --dockerPort, -p <dockerPort>
The port on which the host docker daemon is listening
#### --ca <ca>
Docker host TLS certificate authority file
#### --cert <cert>
Docker host TLS certificate file
#### --key <key>
Docker host TLS key file
#### --tag, -t <tag>
The alias to the generated image
2017-05-12 10:01:37 +00:00
#### --buildArg, -B <arg>
Set a build-time variable (eg. "-B 'ARG=value'"). Can be specified multiple times.
2017-04-26 12:34:40 +00:00
#### --nocache
Don't use docker layer caching when building
2017-05-12 10:01:37 +00:00
2017-06-23 15:20:16 +00:00
#### --squash
Squash newly built layers into a single new layer
2018-11-14 22:26:14 +00:00
# Platform
## join [deviceIp]
Use this command to move a local device to an application on another balena server.
For example, you could provision a device against an openBalena installation
where you perform end-to-end tests and then move it to balenaCloud when it's
ready for production.
Moving a device between applications on the same server is not supported.
If you don't specify a device hostname or IP, this command will automatically
scan the local network for balenaOS devices and prompt you to select one
from an interactive picker. This usually requires root privileges.
Examples:
$ balena join
$ balena join balena.local
$ balena join balena.local --application MyApp
$ balena join 192.168.1.25
$ balena join 192.168.1.25 --application MyApp
### Options
#### --application, -a <application>
The name of the application the device should join
## leave [deviceIp]
Use this command to make a local device leave the balena server it is
provisioned on. This effectively makes the device "unmanaged".
The device entry on the server is preserved after running this command,
so the device can subsequently re-join the server if needed.
If you don't specify a device hostname or IP, this command will automatically
scan the local network for balenaOS devices and prompt you to select one
from an interactive picker. This usually requires root privileges.
Examples:
$ balena leave
$ balena leave balena.local
$ balena leave 192.168.1.25
2017-06-14 21:23:39 +00:00
# Utilities
2018-03-20 17:43:26 +00:00
## util available-drives
2017-06-14 21:23:39 +00:00
Use this command to list your machine's drives usable for writing the OS image to.
Skips the system drives.