balena-cli/doc/cli.markdown

Resin CLI Documentation

This tool allows you to interact with the resin.io api from the comfort of your command line.

Please make sure your system meets the requirements as specified in the README.

Install the CLI

Npm install

The best supported way to install the CLI is from npm:

$ npm install resin-cli -g --production --unsafe-perm

--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.

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:

• Download the latest zip for your OS from https://github.com/resin-io/resin-cli/releases.
• Extract the contents, putting the resin-cli folder somewhere appropriate for your system (e.g. C:/resin-cli, /usr/local/lib/resin-cli, etc).
• Add the resin-cli folder to your PATH. ( Windows instructions, Linux instructions, OSX instructions)
• Running resin in a fresh command line should print the resin CLI help.

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

Once you have the CLI installed, you'll need to log in, so it can access everything in your resin.io account.

To authenticate yourself, run:

$ resin login

You now have access to all the commands referenced below.

Proxy support

The CLI does support HTTP(S) proxies.

You can configure the proxy using several methods (in order of their precedence):

• set the RESINRC_PROXY environment variable in the URL format (with protocol, host, port, and optionally the basic auth),
• use the resin config file (project-specific or user-level) and set the proxy setting. This can be:
  • a string in the URL format,
  • or an object following this format, which allows more control,
• or set the conventional https_proxy / HTTPS_PROXY / http_proxy / HTTP_PROXY environment variable (in the same standard URL format).

Table of contents

• Api keys

  • api-key generate <name>

• Application

  • app create <name>
  • apps
  • app <name>
  • app restart <name>
  • app rm <name>

• Authentication

  • login
  • logout
  • signup
  • whoami

• Device

  • devices
  • device <uuid>
  • devices supported
  • device register <application>
  • device rm <uuid>
  • device identify <uuid>
  • device reboot <uuid>
  • device shutdown <uuid>
  • device public-url enable <uuid>
  • device public-url disable <uuid>
  • device public-url <uuid>
  • device public-url status <uuid>
  • device rename <uuid> [newName]
  • device move <uuid>
  • device init

• Environment Variables

  • envs
  • env rm <id>
  • env add <key> [value]
  • env rename <id> <value>

• Help

  • help [command...]

• Information

  • version

• Keys

  • keys
  • key <id>
  • key rm <id>
  • key add <name> [path]

• Logs

  • logs <uuid>

• Sync

  • sync [uuid]

• SSH

  • ssh [uuid]

• Notes

  • note <|note>

• OS

  • os versions <type>
  • os download <type>
  • os build-config <image> <device-type>
  • os configure <image> [uuid] [deviceApiKey]
  • os initialize <image>

• Config

  • config read
  • config write <key> <value>
  • config inject <file>
  • config reconfigure
  • config generate

• Preload

  • preload <image>

• Push

  • push <application>

• Settings

  • settings

• Wizard

  • quickstart [name]

• Local

  • local configure <target>
  • local flash <image>
  • local logs [deviceIp]
  • local scan
  • local ssh [deviceIp]
  • local push [deviceIp]
  • local stop [deviceIp]

• Deploy

  • build [source]
  • deploy <appName> [image]

• Utilities

  • util available-drives

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.

This key can be used to log into the CLI using 'resin login --token ', or to authenticate requests to the API with an 'Authorization: Bearer ' header.

Examples:

$ resin api-key generate "Jenkins Key"

Application

app create <name>

Use this command to create a new resin.io application.

You can specify the application device type with the --type option. Otherwise, an interactive dropdown will be shown for you to select from.

You can see a list of supported device types with

$ resin devices supported

Examples:

$ resin app create MyApp
$ resin app create MyApp --type raspberry-pi

Options

--type, -t <type>

application device type (Check available types with resin devices supported)

apps

Use this command to list all your applications.

Notice this command only shows the most important bits of information for each app. If you want detailed information, use resin app instead.

Examples:

$ resin apps

app <name>

Use this command to show detailed information for a single application.

Examples:

$ resin app MyApp

app restart <name>

Use this command to restart all devices that belongs to a certain application.

Examples:

$ resin app restart MyApp

app rm <name>

Use this command to remove a resin.io application.

Notice this command asks for confirmation interactively. You can avoid this by passing the --yes boolean option.

Examples:

$ resin app rm MyApp
$ resin app rm MyApp --yes

Options

--yes, -y

confirm non interactively

Authentication

login

Use this command to login to your resin.io account.

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 from the dashboard.

• Credentials: using email/password and 2FA.

• Token: using a session token or API key (experimental) from the preferences page.

Examples:

$ resin login
$ resin login --web
$ resin login --token "..."
$ resin login --credentials
$ resin login --credentials --email johndoe@gmail.com --password secret

Options

--token, -t <token>

session token or API key (experimental)

--web, -w

web-based login

--credentials, -c

credential-based login

--email, -e, -u <email>

email

--password, -p <password>

password

logout

Use this command to logout from your resin.io account.o

Examples:

$ resin logout

signup

Use this command to signup for a resin.io account.

If signup is successful, you'll be logged in to your new user automatically.

Examples:

$ resin signup
Email: johndoe@acme.com
Password: ***********

$ resin whoami
johndoe

whoami

Use this command to find out the current logged in username and email address.

Examples:

$ resin whoami

Device

devices

Use this command to list all devices that belong to you.

You can filter the devices by application by using the --application option.

Examples:

$ resin devices
$ resin devices --application MyApp
$ resin devices --app MyApp
$ resin devices -a MyApp

Options

--application, -a, --app <application>

application name

device <uuid>

Use this command to show information about a single device.

Examples:

$ resin device 7cf02a6

devices supported

Use this command to get the list of all supported devices

Examples:

$ resin devices supported

device register <application>

Use this command to register a device to an application.

Note that device api keys are only supported on ResinOS 2.0.3+

Examples:

$ resin device register MyApp
$ resin device register MyApp --uuid <uuid>
$ resin device register MyApp --uuid <uuid> --device-api-key <existingDeviceKey>

Options

--uuid, -u <uuid>

custom uuid

--deviceApiKey, -k <device-api-key>

custom device key - note that this is only supported on ResinOS 2.0.3+

device rm <uuid>

Use this command to remove a device from resin.io.

Notice this command asks for confirmation interactively. You can avoid this by passing the --yes boolean option.

Examples:

$ resin device rm 7cf02a6
$ resin device rm 7cf02a6 --yes

Options

--yes, -y

confirm non interactively

device identify <uuid>

Use this command to identify a device.

In the Raspberry Pi, the ACT led is blinked several times.

Examples:

$ resin device identify 23c73a1

device reboot <uuid>

Use this command to remotely reboot a device

Examples:

$ resin device reboot 23c73a1

Options

--force, -f

force action if the update lock is set

device shutdown <uuid>

Use this command to remotely shutdown a device

Examples:

$ resin device shutdown 23c73a1

Options

--force, -f

force action if the update lock is set

device public-url enable <uuid>

Use this command to enable public URL for a device

Examples:

$ resin device public-url enable 23c73a1

device public-url disable <uuid>

Use this command to disable public URL for a device

Examples:

$ resin device public-url disable 23c73a1

device public-url <uuid>

Use this command to get the public URL of a device

Examples:

$ resin device public-url 23c73a1

device public-url status <uuid>

Use this command to determine if public URL is enabled for a device

Examples:

$ resin device public-url status 23c73a1

device rename <uuid> [newName]

Use this command to rename a device.

If you omit the name, you'll get asked for it interactively.

Examples:

$ resin device rename 7cf02a6
$ resin device rename 7cf02a6 MyPi

device move <uuid>

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:

$ resin device move 7cf02a6
$ resin device move 7cf02a6 --application MyNewApp

Options

--application, -a, --app <application>

application name

device init

Use this command to download the OS image of a certain application and write it to an SD Card.

Notice this command may ask for confirmation interactively. You can avoid this by passing the --yes boolean option.

Examples:

$ resin device init
$ resin device init --application MyApp

Options

--application, -a, --app <application>

application name

--yes, -y

confirm non interactively

--advanced, -v

show advanced configuration options

--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>

the drive to write the image to, like /dev/sdb or /dev/mmcblk0. Careful with this as you can erase your hard drive. Check resin util available-drives for available options.

--config <config>

path to the config JSON file, see resin os build-config

Environment Variables

envs

Use this command to list all environment variables for a particular application or device.

This command lists all custom environment variables. If you want to see all environment variables, including private ones used by resin, use the verbose option.

At the moment the CLI doesn't fully support multi-container applications, so the following commands will only show service variables, without showing which service they belong to.

Example:

$ resin envs --application MyApp
$ resin envs --application MyApp --verbose
$ resin envs --device 7cf02a6

Options

--application, -a, --app <application>

application name

--device, -d <device>

device uuid

--verbose, -v

show private environment variables

env rm <id>

Use this command to remove an environment variable from an application.

Don't remove resin specific variables, as things might not work as expected.

Notice this command asks for confirmation interactively. You can avoid this by passing the --yes boolean option.

If you want to eliminate a device environment variable, pass the --device boolean option.

Examples:

$ resin env rm 215
$ resin env rm 215 --yes
$ resin env rm 215 --device

Options

--yes, -y

confirm non interactively

--device, -d

device

env add <key> [value]

Use this command to add an enviroment variable to an application.

At the moment the CLI doesn't fully support multi-container applications, so the following commands will only set service variables for the first service in your application.

If value is omitted, the tool will attempt to use the variable's value as defined in your host machine.

Use the --device option if you want to assign the environment variable to a specific device.

If the value is grabbed from the environment, a warning message will be printed. Use --quiet to remove it.

Examples:

$ resin env add EDITOR vim --application MyApp
$ resin env add TERM --application MyApp
$ resin env add EDITOR vim --device 7cf02a6

Options

--application, -a, --app <application>

application name

--device, -d <device>

device uuid

env rename <id> <value>

Use this command to rename an enviroment variable from an application.

Pass the --device boolean option if you want to rename a device environment variable.

Examples:

$ resin env rename 376 emacs
$ resin env rename 376 emacs --device

Options

--device, -d

device

Help

help [command...]

Get detailed help for an specific command.

Examples:

$ resin help apps
$ resin help os download

Options

--verbose, -v

show additional commands

Information

version

Display the Resin CLI version.

Keys

keys

Use this command to list all your SSH keys.

Examples:

$ resin keys

key <id>

Use this command to show information about a single SSH key.

Examples:

$ resin key 17

key rm <id>

Use this command to remove a SSH key from resin.io.

Notice this command asks for confirmation interactively. You can avoid this by passing the --yes boolean option.

Examples:

$ resin key rm 17
$ resin key rm 17 --yes

Options

--yes, -y

confirm non interactively

key add <name> [path]

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:

$ resin key add Main ~/.ssh/id_rsa.pub
$ cat ~/.ssh/id_rsa.pub | resin key add Main

Logs

logs <uuid>

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:

$ resin logs 23c73a1
$ resin logs 23c73a1

Options

--tail, -t

continuously stream output

Sync

sync [uuid]

Warning: 'resin sync' requires an openssh-compatible client and 'rsync' to be correctly installed in your shell environment. For more information (including Windows support) please check the README here: https://github.com/resin-io/resin-cli

Use this command to sync your local changes to a certain device on the fly.

After every 'resin sync' the updated settings will be saved in '/.resin-sync.yml' and will be used in later invocations. You can also change any option by editing '.resin-sync.yml' directly.

Here is an example '.resin-sync.yml' :

$ cat $PWD/.resin-sync.yml
uuid: 7cf02a6
destination: '/usr/src/app'
before: 'echo Hello'
after: 'echo Done'
ignore:
	- .git
	- node_modules/

Command line options have precedence over the ones saved in '.resin-sync.yml'.

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.

Examples:

$ resin sync 7cf02a6 --source . --destination /usr/src/app
$ resin sync 7cf02a6 -s /home/user/myResinProject -d /usr/src/app --before 'echo Hello' --after 'echo Done'
$ resin sync --ignore lib/
$ resin sync --verbose false
$ resin sync

Options

--source, -s <path>

local directory path to synchronize to device

--destination, -d <path>

destination path on device

--ignore, -i <paths>

comma delimited paths to ignore when syncing

--skip-gitignore

do not parse excluded/included files from .gitignore

--skip-restart

do not restart container after syncing

--before, -b <command>

execute a command before syncing

--after, -a <command>

execute a command after syncing

--port, -t <port>

ssh port

--progress, -p

show progress

--verbose, -v

increase verbosity

SSH

ssh [uuid]

Warning: 'resin ssh' requires an openssh-compatible client to be correctly installed in your shell environment. For more information (including Windows support) please check the README here: https://github.com/resin-io/resin-cli

Use this command to get a shell into the running application container of your device.

Examples:

$ resin ssh MyApp
$ resin ssh 7cf02a6
$ resin ssh 7cf02a6 --port 8080
$ resin ssh 7cf02a6 -v
$ resin ssh 7cf02a6 -s

Options

--port, -p <port>

ssh gateway port

--verbose, -v

increase verbosity

--host, -s

access host OS (for devices with Resin OS >= 2.7.5)

--noproxy

don't use the proxy configuration for this connection. Only makes sense if you've configured proxy globally.

Notes

note <|note>

Use this command to set or update a device note.

If note command isn't passed, the tool attempts to read from stdin.

To view the notes, use $ resin device .

Examples:

$ resin note "My useful note" --device 7cf02a6
$ cat note.txt | resin note --device 7cf02a6

Options

--device, -d, --dev <device>

device uuid

OS

os versions <type>

Use this command to show the available resinOS versions for a certain device type. Check available types with resin devices supported

Example:

$ resin os versions raspberrypi3

os download <type>

Use this command to download an unconfigured os image for a certain device type. Check available types with resin devices supported

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.

Examples:

$ resin os download raspberrypi3 -o ../foo/bar/raspberry-pi.img
$ resin os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 1.24.1
$ resin os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version ^1.20.0
$ resin os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version latest
$ resin os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version default
$ resin os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu

Options

--output, -o <output>

output path

--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)

os build-config <image> <device-type>

Use this command to prebuild the OS config once and skip the interactive part of resin os configure.

Example:

$ resin os build-config ../path/rpi3.img raspberrypi3 --output rpi3-config.json
$ resin os configure ../path/rpi3.img 7cf02a6 --config "$(cat rpi3-config.json)"

Options

--advanced, -v

show advanced configuration options

--output, -o <output>

the path to the output JSON file

os configure <image> [uuid] [deviceApiKey]

Use this command to configure a previously downloaded operating system image for the specific device or for an application generally.

Calling this command without --version is not recommended, and may fail in future releases if the OS version cannot be inferred.

Note that device api keys are only supported on ResinOS 2.0.3+.

This command still supports the deprecated format where the UUID and optionally device key 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.

Examples:

$ resin os configure ../path/rpi.img --device 7cf02a6 --version 2.12.7
$ resin os configure ../path/rpi.img --device 7cf02a6 --version 2.12.7 --device-api-key <existingDeviceKey>
$ resin os configure ../path/rpi.img --app MyApp  --version 2.12.7

Options

--advanced, -v

show advanced configuration options

--application, -a, --app <application>

application name

--device, -d <device>

device uuid

--deviceApiKey, -k <device-api-key>

custom device key - note that this is only supported on ResinOS 2.0.3+

--version <version>

a resinOS version

--config <config>

path to the config JSON file, see resin os build-config

os initialize <image>

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.

Examples:

$ resin os initialize ../path/rpi.img --type 'raspberry-pi'

Options

--yes, -y

confirm non interactively

--type, -t <type>

device type (Check available types with resin devices supported)

--drive, -d <drive>

the drive to write the image to, like /dev/sdb or /dev/mmcblk0. Careful with this as you can erase your hard drive. Check resin util available-drives for available options.

Config

config read

Use this command to read the config.json file from the mounted filesystem (e.g. SD card) of a provisioned device"

Examples:

$ resin config read --type raspberry-pi
$ resin config read --type raspberry-pi --drive /dev/disk2

Options

--type, -t <type>

device type (Check available types with resin devices supported)

--drive, -d <drive>

drive

config write <key> <value>

Use this command to write the config.json file to the mounted filesystem (e.g. SD card) of a provisioned device

Examples:

$ resin config write --type raspberry-pi username johndoe
$ resin config write --type raspberry-pi --drive /dev/disk2 username johndoe
$ resin config write --type raspberry-pi files.network/settings "..."

Options

--type, -t <type>

device type (Check available types with resin devices supported)

--drive, -d <drive>

drive

config inject <file>

Use this command to inject a config.json file to the mounted filesystem (e.g. SD card or mounted resinOS image) of a provisioned device"

Examples:

$ resin config inject my/config.json --type raspberry-pi
$ resin config inject my/config.json --type raspberry-pi --drive /dev/disk2

Options

--type, -t <type>

device type (Check available types with resin devices supported)

--drive, -d <drive>

drive

config reconfigure

Use this command to reconfigure a provisioned device

Examples:

$ resin config reconfigure --type raspberry-pi
$ resin config reconfigure --type raspberry-pi --advanced
$ resin config reconfigure --type raspberry-pi --drive /dev/disk2

Options

--type, -t <type>

device type (Check available types with resin devices supported)

--drive, -d <drive>

drive

--advanced, -v

show advanced commands

config generate

Use this command to generate a config.json for a device or application.

Calling this command without --version is not recommended, and may fail in future releases if the OS version cannot be inferred.

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.

Examples:

$ resin config generate --device 7cf02a6 --version 2.12.7
$ resin config generate --device 7cf02a6 --version 2.12.7 --generate-device-api-key
$ resin config generate --device 7cf02a6 --version 2.12.7 --device-api-key <existingDeviceKey>
$ resin config generate --device 7cf02a6 --version 2.12.7 --output config.json
$ resin config generate --app MyApp --version 2.12.7
$ resin config generate --app MyApp --version 2.12.7 --output config.json
$ resin config generate --app MyApp --version 2.12.7 --network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 1

Options

--version <version>

a resinOS version

--application, -a, --app <application>

application name

--device, -d <device>

device uuid

--deviceApiKey, -k <device-api-key>

custom device key - note that this is only supported on ResinOS 2.0.3+

--generate-device-api-key

generate a fresh device key for the device

--output, -o <output>

output

--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

Preload

preload <image>

Warning: "resin preload" requires Docker to be correctly installed in your shell environment. For more information (including Windows support) please check the README here: https://github.com/resin-io/resin-cli .

Use this command to preload an application to a local disk image (or Edison zip archive) with a built release from Resin.io.

Examples: $ resin preload resin.img --app 1234 --commit e1f2592fc6ee949e68756d4f4a48e49bff8d72a0 --splash-image some-image.png $ resin preload resin.img

Options

--app, -a <appId>

id of the application to preload

--commit, -c <hash>

the commit hash for a specific application release to preload, use "latest" to specify the latest release (ignored if no appId is given)

--splash-image, -s <splashImage.png>

path to a png image to replace the splash screen

--dont-check-device-type

Disables check for matching device types in image and application

--pin-device-to-release, -p

Pin the preloaded device to the preloaded release on provision

--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

Push

push <application>

This command can be used to start a build on the remote resin.io cloud builders. The given source directory will be sent to the resin.io builder, and the build will proceed. This can be used as a drop-in replacement for git push to deploy.

Examples:

$ resin push myApp
$ resin push myApp --source <source directory>
$ resin push myApp -s <source directory>

Options

--source, -s <source>

The source that should be sent to the resin builder to be built (defaults to the current directory)

Settings

settings

Use this command to display detected settings

Examples:

$ resin settings

Wizard

quickstart [name]

Use this command to run a friendly wizard to get started with resin.io.

The wizard will guide you through:

- Create an application.
- Initialise an SDCard with the resin.io operating system.
- Associate an existing project directory with your resin.io application.
- Push your project to your devices.

Examples:

$ resin quickstart
$ resin quickstart MyApp

Local

local configure <target>

Use this command to configure or reconfigure a resinOS drive or image.

Examples:

$ resin local configure /dev/sdc
$ resin local configure path/to/image.img

local flash <image>

Use this command to flash a resinOS image to a drive.

Examples:

$ resin local flash path/to/resinos.img
$ resin local flash path/to/resinos.img --drive /dev/disk2
$ resin local flash path/to/resinos.img --drive /dev/disk2 --yes

Options

--yes, -y

confirm non-interactively

--drive, -d <drive>

drive

local logs [deviceIp]

Examples:

$ resin local logs
$ resin local logs -f
$ resin local logs 192.168.1.10
$ resin local logs 192.168.1.10 -f
$ resin local logs 192.168.1.10 -f --app-name myapp

Options

--follow, -f

follow log

--app-name, -a <name>

name of container to get logs from

local scan

Examples:

$ resin local scan
$ resin local scan --timeout 120
$ resin local scan --verbose

Options

--verbose, -v

Display full info

--timeout, -t <timeout>

Scan timeout in seconds

local ssh [deviceIp]

Warning: 'resin local ssh' requires an openssh-compatible client to be correctly installed in your shell environment. For more information (including Windows support) please check the README here: https://github.com/resin-io/resin-cli

Use this command to get a shell into the running application container of your device.

The '--host' option will get you a shell into the Host OS of the resinOS device. 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:

$ resin local ssh
$ resin local ssh --host
$ resin local ssh --container chaotic_water
$ resin local ssh --container chaotic_water --port 22222
$ resin local ssh --verbose

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)

local push [deviceIp]

Warning: 'resin local push' requires an openssh-compatible client and 'rsync' to be correctly installed in your shell environment. For more information (including Windows support) please check the README here: https://github.com/resin-io/resin-cli

Use this command to push your local changes to a container on a LAN-accessible resinOS device on the fly.

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.

After every 'resin local push' the updated settings will be saved in '/.resin-sync.yml' and will be used in later invocations. You can also change any option by editing '.resin-sync.yml' directly.

Here is an example '.resin-sync.yml' :

$ cat $PWD/.resin-sync.yml
local_resinos:
	app-name: local-app
	build-triggers:
		- Dockerfile: abcdefabcdefabcdefabcdefabcdefabcdefabcdef
		- package.json: abcdefabcdefabcdefabcdefabcdefabcdefabcdef
	environment:
		- MY_VARIABLE=123

Command line options have precedence over the ones saved in '.resin-sync.yml'.

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:

$ resin local push
$ resin local push --app-name test-server --build-triggers package.json,requirements.txt
$ resin local push --force-build
$ resin local push --force-build --skip-logs
$ resin local push --ignore lib/
$ resin local push --verbose false
$ resin local push 192.168.2.10 --source . --destination /usr/src/app
$ resin local push 192.168.2.10 -s /home/user/myResinProject -d /usr/src/app --before 'echo Hello' --after 'echo Done'

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.

local stop [deviceIp]

Examples:

$ resin local stop
$ resin local stop --app-name myapp
$ resin local stop --all
$ resin local stop 192.168.1.10
$ resin local stop 192.168.1.10 --app-name myapp

Options

--all

stop all containers

--app-name, -a <name>

name of container to stop

Deploy

build [source]

Use this command to build an image or a complete multicontainer project with the provided docker daemon.

You must provide either an application or a device-type/architecture pair to use the resin Dockerfile pre-processor (e.g. Dockerfile.template -> Dockerfile).

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.

Examples:

$ resin build
$ resin build ./source/
$ resin build --deviceType raspberrypi3 --arch armhf
$ resin build --application MyApp ./source/
$ resin build --docker '/var/run/docker.sock'
$ resin build --dockerHost my.docker.host --dockerPort 2376 --ca ca.pem --key key.pem --cert cert.pem

Options

--arch, -A <arch>

The architecture to build for

--deviceType, -d <deviceType>

The type of device this build is for

--application, -a <application>

The target resin.io application this build is for

--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

--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

--buildArg, -B <arg>

Set a build-time variable (eg. "-B 'ARG=value'"). Can be specified multiple times.

--nocache

Don't use docker layer caching when building

--squash

Squash newly built layers into a single new layer

deploy <appName> [image]

Use this command to deploy an image or a complete multicontainer project to an application, optionally building it first.

Usage: deploy <appName> ([image] | --build [--source build-dir])

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.

To deploy to an app on which you're a collaborator, use resin deploy <appOwnerUsername>/<appName>.

Note: If building with this command, all options supported by resin build are also supported with this command.

Examples:

$ resin deploy myApp
$ resin deploy myApp --build --source myBuildDir/
$ resin deploy myApp myApp/myImage

Options

--source, -s <source>

Specify an alternate source directory; default is the working directory

--build, -b

Force a rebuild before deploy

--nologupload

Don't upload build logs to the dashboard with image (if building)

--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

--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

--buildArg, -B <arg>

Set a build-time variable (eg. "-B 'ARG=value'"). Can be specified multiple times.

--nocache

Don't use docker layer caching when building

--squash

Squash newly built layers into a single new layer

Utilities

util available-drives

Use this command to list your machine's drives usable for writing the OS image to. Skips the system drives.