mirror of
https://github.com/balena-io/balena-cli.git
synced 2024-12-23 23:42:24 +00:00
1674 lines
38 KiB
Markdown
1674 lines
38 KiB
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](https://github.com/resin-io/resin-cli).
|
|
|
|
## 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](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:
|
|
|
|
* 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](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))
|
|
* 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](https://www.npmjs.com/package/resin-settings-client#documentation) (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](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).
|
|
|
|
# Table of contents
|
|
|
|
- Api keys
|
|
|
|
- [api-key generate <name>](#api-key-generate-name-)
|
|
|
|
- Application
|
|
|
|
- [app create <name>](#app-create-name-)
|
|
- [apps](#apps)
|
|
- [app <name>](#app-name-)
|
|
- [app restart <name>](#app-restart-name-)
|
|
- [app rm <name>](#app-rm-name-)
|
|
|
|
- Authentication
|
|
|
|
- [login](#login)
|
|
- [logout](#logout)
|
|
- [signup](#signup)
|
|
- [whoami](#whoami)
|
|
|
|
- Device
|
|
|
|
- [devices](#devices)
|
|
- [device <uuid>](#device-uuid-)
|
|
- [devices supported](#devices-supported)
|
|
- [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-)
|
|
- [device init](#device-init)
|
|
|
|
- Environment Variables
|
|
|
|
- [envs](#envs)
|
|
- [env rm <id>](#env-rm-id-)
|
|
- [env add <key> [value]](#env-add-key-value-)
|
|
- [env rename <id> <value>](#env-rename-id-value-)
|
|
|
|
- Help
|
|
|
|
- [help [command...]](#help-command-)
|
|
|
|
- Information
|
|
|
|
- [version](#version)
|
|
|
|
- Keys
|
|
|
|
- [keys](#keys)
|
|
- [key <id>](#key-id-)
|
|
- [key rm <id>](#key-rm-id-)
|
|
- [key add <name> [path]](#key-add-name-path-)
|
|
|
|
- Logs
|
|
|
|
- [logs <uuid>](#logs-uuid-)
|
|
|
|
- Sync
|
|
|
|
- [sync [uuid]](#sync-uuid-)
|
|
|
|
- SSH
|
|
|
|
- [ssh [uuid]](#ssh-uuid-)
|
|
|
|
- Notes
|
|
|
|
- [note <|note>](#note-note-)
|
|
|
|
- OS
|
|
|
|
- [os versions <type>](#os-versions-type-)
|
|
- [os download <type>](#os-download-type-)
|
|
- [os build-config <image> <device-type>](#os-build-config-image-device-type-)
|
|
- [os configure <image> [uuid] [deviceApiKey]](#os-configure-image-uuid-deviceapikey-)
|
|
- [os initialize <image>](#os-initialize-image-)
|
|
|
|
- Config
|
|
|
|
- [config read](#config-read)
|
|
- [config write <key> <value>](#config-write-key-value-)
|
|
- [config inject <file>](#config-inject-file-)
|
|
- [config reconfigure](#config-reconfigure)
|
|
- [config generate](#config-generate)
|
|
|
|
- Preload
|
|
|
|
- [preload <image>](#preload-image-)
|
|
|
|
- Settings
|
|
|
|
- [settings](#settings)
|
|
|
|
- Wizard
|
|
|
|
- [quickstart [name]](#quickstart-name-)
|
|
|
|
- Local
|
|
|
|
- [local configure <target>](#local-configure-target-)
|
|
- [local flash <image>](#local-flash-image-)
|
|
- [local logs [deviceIp]](#local-logs-deviceip-)
|
|
- [local scan](#local-scan)
|
|
- [local ssh [deviceIp]](#local-ssh-deviceip-)
|
|
- [local push [deviceIp]](#local-push-deviceip-)
|
|
- [local stop [deviceIp]](#local-stop-deviceip-)
|
|
|
|
- Deploy
|
|
|
|
- [build [source]](#build-source-)
|
|
- [deploy <appName> [image]](#deploy-appname-image-)
|
|
|
|
- Utilities
|
|
|
|
- [util available-drives](#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 <key>',
|
|
or to authenticate requests to the API with an 'Authorization: Bearer <key>' 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 <name> 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Note that for now you need to provide the whole UUID for this command to work correctly.
|
|
|
|
This is due to some technical limitations that we plan to address soon.
|
|
|
|
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
|
|
'<source>/.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 <uuid>.
|
|
|
|
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.
|
|
|
|
Note that device api keys are only supported on ResinOS 2.0.3+.
|
|
|
|
This comand 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
|
|
$ resin os configure ../path/rpi.img --device 7cf02a6 --deviceApiKey <existingDeviceKey>
|
|
$ resin os configure ../path/rpi.img --app MyApp
|
|
|
|
### 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+
|
|
|
|
#### --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.
|
|
|
|
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
|
|
$ resin config generate --device 7cf02a6 --device-api-key <existingDeviceKey>
|
|
$ resin config generate --device 7cf02a6 --output config.json
|
|
$ resin config generate --app MyApp
|
|
$ resin config generate --app MyApp --output config.json
|
|
$ resin config generate --app MyApp --network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 1
|
|
|
|
### 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+
|
|
|
|
#### --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
|
|
|
|
#### --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
|
|
|
|
# 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
|
|
'<source>/.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
|
|
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 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.
|
|
|