From 12cdb1463860a1ffef4e8ad44dde32f00369e3b5 Mon Sep 17 00:00:00 2001 From: myarmolinsky Date: Tue, 8 Oct 2024 13:46:19 -0400 Subject: [PATCH] Docs: Show aliases for commands Change-type: patch --- automation/capitanodoc/markdown.ts | 9 ++ docs/balena-cli.md | 171 +++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+) diff --git a/automation/capitanodoc/markdown.ts b/automation/capitanodoc/markdown.ts index e2a35775..8355bf5e 100644 --- a/automation/capitanodoc/markdown.ts +++ b/automation/capitanodoc/markdown.ts @@ -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 diff --git a/docs/balena-cli.md b/docs/balena-cli.md index 781e6119..50fbe551 100644 --- a/docs/balena-cli.md +++ b/docs/balena-cli.md @@ -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 ([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 [:[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