ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2025-02-21 01:42:26 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #1204 from balena-io/1174-add-INSTALL-md-review

Browse Source 
Update README and INSTALL docs (review typos and some rewording)
This commit is contained in:
Paulo Castro 2019-05-02 11:51:23 +01:00 committed by GitHub
commit 2452b42f81
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 93 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
.resinci.yml Normal file
View File

@ -0,0 +1,36 @@
---
npm:
platforms:
- name: linux
os: alpine
architecture: x86_64
node_versions:
- "8"
- "10"
- name: linux
os: alpine
architecture: x86
node_versions:
- "8"
- "10"
- name: darwin
os: macos
architecture: x86_64
node_versions:
- "8"
- "10"
- name: windows
os: windows
architecture: x86_64
node_versions:
- "8"
- "10"
- name: windows
os: windows
architecture: x86
node_versions:
- "8"
- "10"
docker:
publish: false

32
INSTALL.md
View File

@ -4,13 +4,13 @@ The easiest and recommended way of installing the CLI on all platforms (Windows,
to use the [Standalone Installation](#standalone-installation) described below. Some specific CLI
commands have a few extra installation steps: see section [Additional Dependencies](#additional-dependencies).
> **Windows users:** we now have a [YouTube video tutorial](https://www.youtube.com/watch?v=j3JoA1EINUA)
> **Windows users:** We now have a [YouTube video tutorial](https://www.youtube.com/watch?v=j3JoA1EINUA)
for installing and getting started with the balena CLI on Windows!
## Standalone Installation
1. Download the latest zip file for your OS from https://github.com/balena-io/balena-cli/releases.
(Note that "[darwin](https://en.wikipedia.org/wiki/Darwin_(operating_system))" is the
(Note that "[Darwin](https://en.wikipedia.org/wiki/Darwin_(operating_system))" is the
appropriate zip file for macOS.)
2. Extract the zip file contents to any folder you choose. The extracted contents will include a
`balena-cli` folder.
@ -31,7 +31,7 @@ as described above.
## NPM Installation
If you are a Node.js developer, you may wish to install the balena CLI through [npm](https://www.npmjs.com).
If you are a Node.js developer, you may wish to install the balena CLI via [npm](https://www.npmjs.com).
The npm installation involves building native (platform-specific) binary modules, which require
some additional development tools to be installed first:
@ -58,16 +58,16 @@ especially if you're using a user-managed node install such as [nvm](https://git
## Additional Dependencies
* The `balena ssh` command requires a recent version of the `ssh` command-line tool to be available:
* MacOS and Linux usually already have it installed. Otherwise, search for the available packages
* 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](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/).
* Microsoft started distributing a ssh client with Windows 10, which we understand is
automatically installed through Windows Update, but can be manually installed too
([more information](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)).
For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties.
* Microsoft started distributing an SSH client with Windows 10, which we understand is
automatically installed through Windows Update, but can be manually installed too
([more information](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)).
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 will also need to install
* If you need SSH to work behind a proxy, you will also need to install
[`proxytunnel`](http://proxytunnel.sourceforge.net/) (available as a `proxytunnel` package
for Ubuntu, for example).
Check the [README](https://github.com/balena-io/balena-cli/blob/master/README.md) file
@ -75,27 +75,27 @@ especially if you're using a user-managed node install such as [nvm](https://git
* The `balena sync` command (deprecated) currently requires `rsync` (>= 2.6.9) to be installed:
* Linux: `apt-get install rsync`
* MacOS: [Xcode command-line tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/)
* Windows: one option is to use the [MinGW](http://www.mingw.org) shell and install the `msys-rsync` package.
Check the README file for other shell options under Windows.
* macOS: [Xcode command-line tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/)
* Windows: One option is to use the [MinGW](http://www.mingw.org) shell and install the
`msys-rsync` package. Check the README file for other shell options under Windows.
## Configuring SSH keys
The `balena ssh` command requires a SSH key to be added to your balena account. If you had
The `balena ssh` command requires an SSH key to be added to your balena account. If you had
already added a SSH key in order to [deploy with 'git push'](https://www.balena.io/docs/learn/getting-started/raspberrypi3/nodejs/#adding-an-ssh-key),
then you are probably done and may skip this section. You can check whether you already have
a SSH key in your balena account with the `balena keys` command, or by visiting the
an SSH key in your balena account with the `balena keys` command, or by visiting the
[balena web dashboard](https://dashboard.balena-cloud.com/), clicking on your name -> Preferences
-> SSH Keys.
> Note: a "SSH key" actually consists of a public/private key pair. A typical name for the private
> Note: An "SSH key" actually consists of a public/private key pair. A typical name for the private
> key file is "id_rsa", and a typical name for the public key file is "id_rsa.pub". Both key files
> are saved to your computer (with the private key optionally protected by a password), but only
> the public key is saved to your balena account. This means that if you change computers or
> otherwise lose the private key, _you cannot recover the private key through your balena account._
> You can however add new keys, and delete the old ones.
If you don't have a SSH key in you balena account:
If you don't have an SSH key in your balena account:
* If you have an existing SSH key in your computer that you would like to use, you can add it
to your balena account through the balena web dashboard (Preferences -> SSH Keys), or through

31
README.md
View File

@ -10,7 +10,7 @@ The official balena CLI tool.
The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the
[balena API](https://www.balena.io/docs/reference/api/overview/) through a terminal window
on Linux, MacOS or Windows. You can also write shell scripts around it, or import its Node.js
on Linux, macOS or Windows. You can also write shell scripts around it, or import its Node.js
modules to use it programmatically.
As an [open-source project on GitHub](https://github.com/balena-io/balena-cli/), your contribution
is also welcome!
@ -23,27 +23,26 @@ Check the [balena CLI installation instructions on GitHub](https://github.com/ba
### Choosing a shell (command prompt/terminal)
On Linux and MacOS, `bash` is the standard and recommended shell for use with the balena CLI.
> **bash command auto completion**
`bash` command auto completion can be enabled by copying the
[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash)
file to the default bash completions directory (usually `/etc/bash_completion.d/`), or by appending
it to `~/.bash_completion`.
On Windows, we support the standard Windows Command Prompt (`cmd.exe`) and the Windows
[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6).
We are aware of users also having a good experience with alternative shells, including:
On **Windows,** the standard Command Prompt (`cmd.exe`) and
[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6)
are supported. We are aware of users also having a good experience with alternative shells,
including:
* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
(a.k.a. Microsoft's "bash for Windows 10").
* [Git for Windows](https://git-for-windows.github.io/).
* [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too.
On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command
auto completion may be enabled by copying the
[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash)
file to your system's `bash_completion` directory: check [Docker's command completion
guide](https://docs.docker.com/compose/completion/) for system setup instructions.
### Logging in
Several CLI commands require access to your balenaCloud account, for example in order to push
a new release to your app. Those commands require creating a CLI login session by running:
Several CLI commands require access to your balenaCloud account, for example in order to push a
new release to your application. Those commands require creating a CLI login session by running:
```sh
$ balena login
@ -57,8 +56,8 @@ HTTP(S) proxies can be configured through any of the following methods, in order
optionally basic auth).
* Alternatively, use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation)
(project-specific or user-level) and set the \`proxy\` setting. It can be:
* a string in URL format, or
* an object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control).
* A string in URL format, or
* An object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control).
* Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\`
environment variable (in the same standard URL format).

9
automation/capitanodoc/capitanodoc.ts
View File

@ -132,7 +132,7 @@ const capitanoDoc = {
export async function getCapitanoDoc(): Promise<typeof capitanoDoc> {
const readmePath = path.join(__dirname, '..', '..', 'README.md');
const mdParser = new MarkdownFileParser(readmePath);
return Promise.all([
const sections: string[] = await Promise.all([
mdParser.getSectionOfTitle('About').then((sectionLines: string) => {
// delete the title of the 'About' section for the web page
const match = /^(#+)\s+.+?\n\s*([^]*)/.exec(sectionLines);
@ -145,8 +145,7 @@ export async function getCapitanoDoc(): Promise<typeof capitanoDoc> {
mdParser.getSectionOfTitle('Installation'),
mdParser.getSectionOfTitle('Getting Started'),
mdParser.getSectionOfTitle('Support, FAQ and troubleshooting'),
]).then((sections: string[]) => {
capitanoDoc.introduction = sections.join('\n');
return capitanoDoc;
});
]);
capitanoDoc.introduction = sections.join('\n');
return capitanoDoc;
}

17
automation/capitanodoc/index.ts
View File

@ -40,7 +40,6 @@ export async function renderMarkdown(): Promise<string> {
};
for (const file of commandCategory.files) {
// tslint:disable-next-line:no-var-requires
const actions: any = require(path.join(process.cwd(), file));
if (actions.signature) {
@ -63,15 +62,13 @@ export async function renderMarkdown(): Promise<string> {
* Print the CLI docs markdown to stdout.
* See package.json for how the output is redirected to a file.
*/
function printMarkdown() {
renderMarkdown()
.then((mdDocs: string) => {
console.log(mdDocs);
})
.catch((error: Error) => {
console.error(error);
process.exit(1);
});
async function printMarkdown() {
try {
console.log(await renderMarkdown());
} catch (error) {
console.error(error);
process.exit(1);
}
}
printMarkdown();

31
doc/cli.markdown
View File

@ -2,7 +2,7 @@
The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the
[balena API](https://www.balena.io/docs/reference/api/overview/) through a terminal window
on Linux, MacOS or Windows. You can also write shell scripts around it, or import its Node.js
on Linux, macOS or Windows. You can also write shell scripts around it, or import its Node.js
modules to use it programmatically.
As an [open-source project on GitHub](https://github.com/balena-io/balena-cli/), your contribution
is also welcome!
@ -15,27 +15,26 @@ Check the [balena CLI installation instructions on GitHub](https://github.com/ba
### Choosing a shell (command prompt/terminal)
On Linux and MacOS, `bash` is the standard and recommended shell for use with the balena CLI.
> **bash command auto completion**
`bash` command auto completion can be enabled by copying the
[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash)
file to the default bash completions directory (usually `/etc/bash_completion.d/`), or by appending
it to `~/.bash_completion`.
On Windows, we support the standard Windows Command Prompt (`cmd.exe`) and the Windows
[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6).
We are aware of users also having a good experience with alternative shells, including:
On **Windows,** the standard Command Prompt (`cmd.exe`) and
[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6)
are supported. We are aware of users also having a good experience with alternative shells,
including:
* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
(a.k.a. Microsoft's "bash for Windows 10").
* [Git for Windows](https://git-for-windows.github.io/).
* [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too.
On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command
auto completion may be enabled by copying the
[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash)
file to your system's `bash_completion` directory: check [Docker's command completion
guide](https://docs.docker.com/compose/completion/) for system setup instructions.
### Logging in
Several CLI commands require access to your balenaCloud account, for example in order to push
a new release to your app. Those commands require creating a CLI login session by running:
Several CLI commands require access to your balenaCloud account, for example in order to push a
new release to your application. Those commands require creating a CLI login session by running:
```sh
$ balena login
@ -49,8 +48,8 @@ HTTP(S) proxies can be configured through any of the following methods, in order
optionally basic auth).
* Alternatively, use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation)
(project-specific or user-level) and set the \`proxy\` setting. It can be:
* a string in URL format, or
* an object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control).
* A string in URL format, or
* An object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control).
* Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\`
environment variable (in the same standard URL format).