490f833a33
Change-type: patch Signed-off-by: Cameron Diver <cameron@balena.io> |
||
---|---|---|
.github | ||
automation | ||
bin | ||
doc | ||
lib | ||
tests | ||
typings | ||
.editorconfig | ||
.gitignore | ||
.hound.yml | ||
.prettierrc | ||
.travis.yml | ||
appveyor.yml | ||
balena-completion.bash | ||
capitanodoc.ts | ||
CHANGELOG.md | ||
coffeelint.json | ||
gulpfile.coffee | ||
LICENSE | ||
package.json | ||
README.md | ||
TROUBLESHOOTING.md | ||
tsconfig.json |
balena CLI
The official balena CLI tool.
Getting Started
The easiest and recommended way of installing the CLI on all platforms (Linux, MacOS, Windows)
is to use the Standalone Install described below. Some specific CLI commands like balena ssh
and balena sync
have additional dependencies: see section Additional Dependencies.
Windows users: we now have a YouTube video tutorial for installing and getting started with the balena CLI on Windows!
Standalone install
- 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 yourPATH
(Windows instructions, Linux instructions, OSX instructions) - Running
balena
in a fresh command line should print the balena CLI help. See Windows Support section below for some notes regarding the shell.
To update the CLI to a new version, simply download a new release and replace the extracted folder.
NPM install
If you are a Node.js developer, you may wish to install the balena CLI through npm[https://www.npmjs.com]. The npm installation involves building native (platform-specific) binary modules, for which there are some pre-requisites:
- Node.js version 6 or above (soon version 8 or above)
- Python 2.7
- g++ compiler
- make
- git
- Under Windows, the
windows-build-tools
npm package should be installed too, running the following command in an administrator console (available as 'Command Prompt (Admin)' when pressing Windows+X in Windows 7+) :
npm install -g --production windows-build-tools
With those in place, the CLI installation command is:
$ npm install balena-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.
Additional Dependencies
-
The
balena ssh
command requires a recent version of thessh
command-line tool to be available:-
MacOS and Linux usually already have it installed. Otherwise, search for the available packages on your specific Linux distribution, or for the Mac consider the Xcode command-line tools or homebrew.
-
Microsoft released an OpenSSH version of ssh for Windows 10, which we understand is automatically installed through Windows Update, but can be manually installed too. More information here. For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties.
-
If you need
ssh
to work behind a proxy, you also needproxytunnel
installed (available asproxytunnel
package for Ubuntu, for example).
-
-
The
balena sync
command currently requiresrsync
(>= 2.6.9) to be installed:- Linux:
apt-get install rsync
- MacOS: Xcode command-line tools or homebrew
- Windows: use MinGW as described in the Windows Support section.
- Linux:
Windows Support
We aim at supporting the standard Windows Command Prompt (cmd.exe
) and the Windows PowerShell.
Some CLI commands like balena sync
and balena ssh
have not been thoroughly tested with the standard Windows shells. We are aware of users having a good experience with alternative shells, including:
- Microsoft's Windows Subsystem for Linux (a.k.a. Microsoft's "bash for Windows 10").
- Git for Windows.
- MinGW
- Install MinGW.
- Install the
msys-rsync
andmsys-openssh
packages. - Add MinGW to the
%PATH%
if this hasn't been done by the installer already. The location where the binaries are places is usuallyC:\MinGW\msys\1.0\bin
, but it can vary if you selected a different location in the installer. - Copy your SSH keys to
%homedrive%%homepath\.ssh
. - If you need
ssh
to work behind the proxy you also need to install proxytunnel
Login
$ balena login
(Typically useful, but not strictly required for all commands)
Run commands
Take a look at the full command documentation at https://balena.io/docs/tools/cli/, or by running balena help
.
Bash completions
Optionally you can enable tab completions for the bash shell, enabling the shell to provide additional context and automatically complete arguments tobalena
. To enable bash completions, copy the balena-completion.bash
file to the default bash completions directory (usually /etc/bash_completion.d/
) or append it to the end of ~/.bash_completion
.
FAQ
Where is my configuration file?
The per-user configuration file lives in $HOME/.balenarc.yml
or %UserProfile%\_balenarc.yml
, in Unix based operating systems and Windows respectively.
The balena CLI also attempts to read a balenarc.yml
file in the current directory, which takes precedence over the per-user configuration file.
How do I point the balena CLI to staging?
The easiest way is to set the BALENARC_BALENA_URL=balena-staging.com
environment variable.
Alternatively, you can edit your configuration file and set balenaUrl: balena-staging.com
to persist this setting.
How do I make the balena CLI persist data in another directory?
The balena CLI persists your session token, as well as cached images in $HOME/.balena
or %UserProfile%\_balena
.
Pointing the balena CLI to persist data in another location is necessary in certain environments, like a server, where there is no home directory, or a device running balenaOS, which erases all data after a restart.
You can accomplish this by setting BALENARC_DATA_DIRECTORY=/opt/balena
or adding dataDirectory: /opt/balena
to your configuration file, replacing /opt/balena
with your desired directory.
Support
If you're having any problems or would like to get in touch:
- Check our troubleshooting guide
- Ask us a question through the balenaCloud forum: https://forums.balena.io/c/balena-cloud
- For bug reports or feature requests, have a look at the GitHub issues or create a new one at: https://github.com/balena-io/balena-cli/issues/
Development guidelines
The CLI was originally written in CoffeeScript, but we have decided to migrate to TypeScript in order to take advantage of static typing and formal programming interfaces. The migration is taking place gradually, as part of maintenance work or the implementation of new features.
After cloning this repository and running npm install
you can build the CLI using npm run build
.
You can then run the generated build using ./bin/balena
.
In order to ease development:
- you can build the CLI using the
npm run build:fast
variant which skips some of the build steps or - you can use
./bin/balena-dev
which live transpiles the sources of the CLI.
In either case, before opening a PR make sure to also test your changes after doing a full build with npm run build
.
License
The project is licensed under the Apache 2.0 license.