ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2024-12-18 21:27:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Docs: Show aliases for commands

Browse Source 
Change-type: patch
This commit is contained in:
myarmolinsky 2024-10-08 13:46:19 -04:00
parent b936c51941
commit 12cdb14638
2 changed files with 180 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
automation/capitanodoc/markdown.ts
View File

@ -24,6 +24,15 @@ import type { Category, Document, OclifCommand } from './doc-types';
function renderOclifCommand(command: Category['commands'][0]): string[] {
const result = [`## ${ent.encode(command.name || '')}`];
if (command.aliases?.length) {
result.push('### Aliases');
result.push(command.aliases.map((alias) => `- \`${alias}\``).join('\n'));
result.push(
`\nTo use one of the aliases, replace \`${command.name}\` with the alias.`,
);
}
result.push('### Description');
const description = (command.description || '')
.split('\n')
.slice(1) // remove the first line, which oclif uses as help header

171
docs/balena-cli.md
View File

@ -321,6 +321,8 @@ are encouraged to regularly update the balena CLI to the latest version.
## api-key generate
### Description
Generate a new balenaCloud API key for the current user, with the given
name. The key will be logged to the console.
@ -341,6 +343,8 @@ the API key name
## api-key revoke
### Description
Revoke balenaCloud API keys with the given
comma-separated list of ids.
@ -361,6 +365,8 @@ the API key ids
## api-keys
### Description
Print a list of balenaCloud API keys.
Print a list of balenaCloud API keys for the current user or for a specific fleet with the `--fleet` option.
@ -383,6 +389,8 @@ fleet name or slug (preferred)
## app create
### Description
Create a new balena app.
You can specify the organization the app should belong to using
@ -426,6 +434,8 @@ app device type (Check available types with `balena devices supported`)
## login
### Description
Login to your balena account.
This command will prompt you to login using the following login types:
@ -487,6 +497,8 @@ Hides warning for experimental features
## logout
### Description
Logout from your balena account.
Examples:
@ -495,6 +507,8 @@ Examples:
## whoami
### Description
Get the username and email address of the currently logged in user.
Examples:
@ -505,6 +519,8 @@ Examples:
## block create
### Description
Create a new balena block.
You can specify the organization the block should belong to using
@ -548,6 +564,8 @@ block device type (Check available types with `balena devices supported`)
## config generate
### Description
Generate a config.json file for a device or fleet.
The target balenaOS version must be specified with the --version option.
@ -658,6 +676,8 @@ expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)
## config inject
### Description
Inject a 'config.json' file to a balenaOS image file or attached SD card or
USB stick.
@ -683,6 +703,8 @@ path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
## config read
### Description
Read the 'config.json' file of a balenaOS image file or attached SD card or
USB stick.
@ -707,6 +729,8 @@ produce JSON output instead of tabular output
## config reconfigure
### Description
Interactively reconfigure a balenaOS image file or attached media.
This command extracts the device UUID from the 'config.json' file of the
@ -738,6 +762,8 @@ balenaOS version, for example "2.32.0" or "2.44.0+rev1"
## config write
### Description
Write a key-value pair to the 'config.json' file of a balenaOS image file or
attached SD card or USB stick.
@ -770,6 +796,8 @@ path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
## build
### Description
Use this command to build an image or a complete multicontainer project with
the provided docker daemon in your development machine or balena device.
(See also the `balena push` command for the option of building images in the
@ -969,6 +997,8 @@ Docker host TLS key file
## deploy
### Description
Usage: `deploy <fleet> ([image] | --build [--source build-dir])`
Use this command to deploy an image or a complete multicontainer project to a
@ -1196,6 +1226,8 @@ Docker host TLS key file
## device deactivate
### Description
Deactivate a device.
Note this command asks for confirmation interactively.
@ -1220,6 +1252,8 @@ answer "yes" to all questions (non interactive use)
## device identify
### Description
Identify a device by making the ACT LED blink (Raspberry Pi).
Examples:
@ -1236,6 +1270,8 @@ the uuid of the device to identify
## device
### Description
Show information about a single device.
The --json option is recommended when scripting the output of this command,
@ -1268,6 +1304,8 @@ open device dashboard page
## device init
### Description
Register a new device in the selected fleet, download the OS image for the
fleet's default device type, configure the image and write it to an SD card.
This command effectively combines several other balena CLI commands in one,
@ -1353,6 +1391,15 @@ expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)
## device list
### Aliases
- `devices`
To use one of the aliases, replace `device list` with the alias.
### Description
List all of your devices.
Devices can be filtered by fleet with the `--fleet` option.
@ -1391,6 +1438,8 @@ produce JSON output instead of tabular output
## device local-mode
### Description
Output current local mode status, or enable/disable local mode
for specified device.
@ -1423,6 +1472,8 @@ output boolean indicating local mode status
## device move
### Description
Move one or more devices to another fleet.
If --fleet is omitted, the fleet will be prompted for interactively.
@ -1458,6 +1509,8 @@ fleet name or slug (preferred)
## device os-update
### Description
Start a Host OS update for a device.
Note this command will ask for confirmation interactively.
@ -1494,6 +1547,8 @@ answer "yes" to all questions (non interactive use)
## device pin
### Description
Pin a device to a release.
Note, if the commit is omitted, the currently pinned release will be printed, with instructions for how to see a list of releases
@ -1517,6 +1572,8 @@ the commit of the release for the device to get pinned to
## device public-url
### Description
This command will output the current public URL for the
specified device. It can also enable or disable the URL,
or output the enabled status, using the respective options.
@ -1550,6 +1607,8 @@ determine if public URL is enabled
## device purge
### Description
Purge data from a device.
This will clear the device's "/data" directory.
@ -1571,6 +1630,8 @@ comma-separated list (no blank spaces) of device UUIDs
## device reboot
### Description
Remotely reboot a device.
Examples:
@ -1591,6 +1652,8 @@ force action if the update lock is set
## device register
### Description
Register a new device with a balena fleet.
If --uuid is not provided, a new UUID will be automatically assigned.
@ -1630,6 +1693,8 @@ device type slug (run 'balena devices supported' for possible values)
## device rename
### Description
Rename a device.
Note, if the name is omitted, it will be prompted for interactively.
@ -1653,6 +1718,8 @@ the new name for the device
## device restart
### Description
Restart containers on a device.
If the --service flag is provided, then only those services' containers
will be restarted, otherwise all containers on the device will be restarted.
@ -1683,6 +1750,8 @@ comma-separated list (no blank spaces) of service names to restart
## device rm
### Description
Remove one or more devices from balena.
Note this command asks for confirmation interactively.
@ -1708,6 +1777,8 @@ answer "yes" to all questions (non interactive use)
## device shutdown
### Description
Remotely shutdown a device.
Examples:
@ -1728,6 +1799,8 @@ force action if the update lock is set
## device start-service
### Description
Start containers on a device.
Multiple devices and services may be specified with a comma-separated list
@ -1752,6 +1825,8 @@ comma-separated list (no blank spaces) of service names
## device stop-service
### Description
Stop containers on a device.
Multiple devices and services may be specified with a comma-separated list
@ -1776,6 +1851,8 @@ comma-separated list (no blank spaces) of service names
## device track-fleet
### Description
Make a device track the fleet's pinned release.
Examples:
@ -1792,6 +1869,8 @@ the uuid of the device to make track the fleet's release
## devices supported
### Description
List the supported device types (like 'raspberrypi3' or 'intel-nuc').
The --json option is recommended when scripting the output of this command,
@ -1815,6 +1894,8 @@ produce JSON output instead of tabular output
## env add
### Description
Add an environment or config variable to one or more fleets, devices or
services, as selected by the respective command-line options. Either the
--fleet or the --device option must be provided, and either may be be
@ -1890,6 +1971,8 @@ service name
## env rename
### Description
Change the value of a configuration or environment variable for a fleet,
device or service, as selected by command-line options.
@ -1953,6 +2036,8 @@ select a service variable (may be used together with the --device option)
## env rm
### Description
Remove a configuration or environment variable from a fleet, device
or service, as selected by command-line options.
@ -2020,6 +2105,8 @@ do not prompt for confirmation before deleting the variable
## envs
### Description
List the environment or configuration variables of a fleet, device or
service, as selected by the respective command-line options. (A service
corresponds to a Docker image/container in a microservices fleet.)
@ -2097,6 +2184,8 @@ service name
## fleet create
### Description
Create a new balena fleet.
You can specify the organization the fleet should belong to using
@ -2138,6 +2227,8 @@ fleet device type (Check available types with `balena devices supported`)
## fleet
### Description
Display detailed information about a single fleet.
Fleets may be specified by fleet name or slug. Fleet slugs are
@ -2174,6 +2265,8 @@ produce JSON output instead of tabular output
## fleet pin
### Description
Pin a fleet to a release.
Note, if the commit is omitted, the currently pinned release will be printed, with instructions for how to see a list of releases
@ -2197,6 +2290,8 @@ the commit of the release for the fleet to get pinned to
## fleet purge
### Description
Purge data from all devices belonging to a fleet.
This will clear the fleet's '/data' directory.
@ -2225,6 +2320,8 @@ fleet name or slug (preferred)
## fleet rename
### Description
Rename a fleet.
Note, if the `newName` parameter is omitted, it will be
@ -2260,6 +2357,8 @@ the new name for the fleet
## fleet restart
### Description
Restart all devices belonging to a fleet.
Fleets may be specified by fleet name or slug. Fleet slugs are
@ -2287,6 +2386,8 @@ fleet name or slug (preferred)
## fleet rm
### Description
Permanently remove a fleet.
The --yes option may be used to avoid interactive confirmation.
@ -2321,6 +2422,8 @@ answer "yes" to all questions (non interactive use)
## fleet track-latest
### Description
Make this fleet track the latest release.
Examples:
@ -2338,6 +2441,8 @@ the slug of the fleet to make track the latest release
## fleets
### Description
List all your balena fleets.
For detailed information on a particular fleet, use
@ -2357,6 +2462,8 @@ produce JSON output instead of tabular output
## local configure
### Description
Configure or reconfigure a balenaOS drive or image.
Examples:
@ -2374,6 +2481,8 @@ path of drive or image to configure
## local flash
### Description
Flash a balenaOS image to a drive.
Image file may be one of: .img|.zip|.gz|.bz2|.xz
@ -2408,6 +2517,8 @@ answer "yes" to all questions (non interactive use)
## logs
### Description
Show logs for a specific device.
By default, the command prints all log messages and exits.
@ -2465,6 +2576,8 @@ Only show system logs. This can be used in combination with --service.
## scan
### Description
Scan for balenaOS devices on your local network.
The output includes device information collected through balenaEngine for
@ -2494,6 +2607,8 @@ produce JSON output instead of tabular output
## ssh
### Description
Start a shell on a local or remote device. If a service name is not provided,
a shell will be opened on the host OS.
@ -2559,6 +2674,8 @@ bypass global proxy configuration for the ssh connection
## tunnel
### Description
Use this command to open local TCP ports that tunnel to listening sockets in a
balenaOS device.
@ -2612,6 +2729,8 @@ port mapping in the format <remotePort>[:[localIP:]localPort]
## notes
### Description
Set or update a device note. If the note argument is not provided,
it will be read from stdin.
@ -2642,6 +2761,8 @@ device UUID
## orgs
### Description
list all the organizations that you are a member of.
Examples:
@ -2654,6 +2775,8 @@ Examples:
## os build-config
### Description
Interactively generate a configuration file that can then be used as
non-interactive input by the 'balena os configure' command.
@ -2684,6 +2807,8 @@ path to output JSON file
## os configure
### Description
Configure a previously downloaded balenaOS image for a specific device type
or fleet.
@ -2809,6 +2934,8 @@ expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)
## os download
### Description
Download an unconfigured OS image for the specified device type.
Check available device types with 'balena devices supported'.
@ -2864,6 +2991,8 @@ or 'menu-esr' (interactive menu, ESR versions)
## os initialize
### Description
Initialize an os image for a device with a previously
configured operating system image and flash the
an external storage drive or the device's storage
@ -2901,6 +3030,8 @@ answer "yes" to all questions (non interactive use)
## os versions
### Description
Show the available balenaOS versions for the given device type.
Check available types with `balena devices supported`.
@ -2931,6 +3062,8 @@ include pre-release balenaOS versions
## join
### Description
Move a local device to a fleet on another balena server, causing
the device to "join" the new server. The device must be running balenaOS.
@ -2983,6 +3116,8 @@ the interval in minutes to check for updates
## leave
### Description
Remove a local device from its balena fleet, causing the device to
"leave" the server it is provisioned on. This effectively makes the device
"unmanaged". The device must be running balenaOS.
@ -3012,6 +3147,8 @@ the device IP or hostname
## preload
### Description
Preload a release (service images/containers) from a balena fleet, and optionally
a balenaOS splash screen, in a previously downloaded '.img' balenaOS image file
in the local disk (a zip file is only accepted for the Intel Edison device type).
@ -3120,6 +3257,8 @@ Docker host TLS key file
## push
### Description
Build release images on balenaCloud servers or on a local mode device.
When building on the balenaCloud servers, the given source directory will be
@ -3347,6 +3486,8 @@ The notes for this release
## release finalize
### Description
Finalize a release. Releases can be "draft" or "final", and this command
changes a draft release into a final release. Draft releases can be created
with the `--draft` option of the `balena build` or `balena deploy`
@ -3373,6 +3514,8 @@ the commit or ID of the release to finalize
## release
### Description
The --json option is recommended when scripting the output of this command,
because field names are less likely to change in JSON format and because it
better represents data types like arrays, empty strings and null values.
@ -3403,6 +3546,8 @@ Return the release composition
## release invalidate
### Description
Invalidate a release.
Invalid releases are not automatically deployed to devices tracking the latest
@ -3424,6 +3569,8 @@ the commit or ID of the release to invalidate
## release validate
### Description
Validate a release.
Valid releases are automatically deployed to devices tracking the latest
@ -3444,6 +3591,8 @@ the commit or ID of the release to validate
## releases
### Description
List all releases of the given fleet.
Fleets may be specified by fleet name or slug. Slugs are recommended because
@ -3482,6 +3631,8 @@ produce JSON output instead of tabular output
## settings
### Description
Use this command to display the current balena CLI settings.
Examples:
@ -3494,6 +3645,8 @@ Examples:
## key add
### Description
Add an SSH key to the balenaCloud account of the logged in user.
If `path` is omitted, the command will attempt to read the SSH key from stdin.
@ -3533,6 +3686,8 @@ the path to the public key file
## key
### Description
Display a single SSH key registered in balenaCloud for the logged in user.
Examples:
@ -3549,6 +3704,8 @@ balenaCloud ID for the SSH key
## key rm
### Description
Remove a single SSH key registered in balenaCloud for the logged in user.
The --yes option may be used to avoid interactive confirmation.
@ -3572,6 +3729,8 @@ answer "yes" to all questions (non interactive use)
## keys
### Description
List all SSH keys registered in balenaCloud for the logged in user.
Examples:
@ -3584,6 +3743,8 @@ Examples:
## support
### Description
Grant or revoke balena support agent access to devices or fleets
on balenaCloud. (This command does not apply to openBalena.)
Access will be automatically revoked once the specified duration has elapsed.
@ -3634,6 +3795,8 @@ length of time to enable support for, in (h)ours or (d)ays, e.g. 12h, 2d
## tag rm
### Description
Remove a tag from a fleet, device or release.
Fleets may be specified by fleet name or slug. Fleet slugs are
@ -3676,6 +3839,8 @@ release id
## tag set
### Description
Set a tag on a fleet, device or release.
You can optionally provide a value to be associated with the created
@ -3729,6 +3894,8 @@ release id
## tags
### Description
List all tags and their values for the specified fleet, device or release.
Fleets may be specified by fleet name or slug. Fleet slugs are
@ -3767,6 +3934,8 @@ release id
## util available-drives
### Description
List available drives which are usable for writing an OS image to.
Does not list system drives.
@ -3776,6 +3945,8 @@ Does not list system drives.
## version
### Description
Display version information for the balena CLI and/or Node.js. Note that the
balena CLI executable installers for Windows and macOS, and the standalone
zip packages, ship with a built-in copy of Node.js. In this case, the