diff --git a/automation/capitanodoc/doc-types.d.ts b/automation/capitanodoc/doc-types.d.ts index c0b27752..600c611a 100644 --- a/automation/capitanodoc/doc-types.d.ts +++ b/automation/capitanodoc/doc-types.d.ts @@ -26,7 +26,7 @@ export interface Document { export interface Category { title: string; - commands: OclifCommand[]; + commands: Array; } export { OclifCommand }; diff --git a/automation/capitanodoc/index.ts b/automation/capitanodoc/index.ts index 4bb8047a..baf77a57 100644 --- a/automation/capitanodoc/index.ts +++ b/automation/capitanodoc/index.ts @@ -18,7 +18,6 @@ import * as path from 'path'; import { getCapitanoDoc } from './capitanodoc'; import type { Category, Document, OclifCommand } from './doc-types'; import * as markdown from './markdown'; -import { stripIndent } from '../../src/utils/lazy'; /** * Generates the markdown document (as a string) for the CLI documentation @@ -39,7 +38,7 @@ export async function renderMarkdown(): Promise { }; for (const jsFilename of commandCategory.files) { - category.commands.push(...(await importOclifCommands(jsFilename))); + category.commands.push(await importOclifCommands(jsFilename)); } result.categories.push(category); } @@ -47,51 +46,23 @@ export async function renderMarkdown(): Promise { return markdown.render(result); } -// Help is now managed via a plugin -// This fake command allows capitanodoc to include help in docs -class FakeHelpCommand { - description = stripIndent` - List balena commands, or get detailed help for a specific command. +async function importOclifCommands(jsFilename: string) { + const command = (await import(path.join(process.cwd(), jsFilename))) + .default as OclifCommand; - List balena commands, or get detailed help for a specific command. - `; - - examples = [ - '$ balena help', - '$ balena help login', - '$ balena help os download', - ]; - - args = { - command: { - description: 'command to show help for', - }, - }; - - usage = 'help [command]'; - - flags = { - verbose: { - description: 'show additional commands', - char: '-v', - }, - }; -} - -async function importOclifCommands( - jsFilename: string, -): Promise { - // TODO: Currently oclif commands with no `usage` overridden will cause - // an error when parsed. This should be improved so that `usage` does not have - // to be overridden if not necessary. - - const command: OclifCommand = - jsFilename === 'help' - ? (new FakeHelpCommand() as unknown as OclifCommand) - : ((await import(path.join(process.cwd(), jsFilename))) - .default as OclifCommand); - - return [command]; + return { + ...command, + // build/commands/device/index.js -> device + // build/commands/device/list.js -> device list + name: jsFilename + .split('/') + .slice(2) + .join(' ') + .split('.') + .slice(0, 1) + .join(' ') + .split(' index')[0], + } as Category['commands'][0]; } /** diff --git a/automation/capitanodoc/markdown.ts b/automation/capitanodoc/markdown.ts index 44cfc422..e2a35775 100644 --- a/automation/capitanodoc/markdown.ts +++ b/automation/capitanodoc/markdown.ts @@ -22,8 +22,8 @@ import { getManualSortCompareFunction } from '../../src/utils/helpers'; import { capitanoizeOclifUsage } from '../../src/utils/oclif-utils'; import type { Category, Document, OclifCommand } from './doc-types'; -function renderOclifCommand(command: OclifCommand): string[] { - const result = [`## ${ent.encode(command.usage || '')}`]; +function renderOclifCommand(command: Category['commands'][0]): string[] { + const result = [`## ${ent.encode(command.name || '')}`]; const description = (command.description || '') .split('\n') .slice(1) // remove the first line, which oclif uses as help header @@ -80,7 +80,7 @@ function renderToc(categories: Category[]): string[] { result.push( category.commands .map((command) => { - const signature = capitanoizeOclifUsage(command.usage); + const signature = capitanoizeOclifUsage(command.name); return `\t- [${ent.encode(signature)}](${getAnchor(signature)})`; }) .join('\n'), diff --git a/docs/balena-cli.md b/docs/balena-cli.md index 28a46c79..898d3cbb 100644 --- a/docs/balena-cli.md +++ b/docs/balena-cli.md @@ -162,13 +162,13 @@ are encouraged to regularly update the balena CLI to the latest version. - API Keys - - [api-key generate <name>](#api-key-generate-name) - - [api-key revoke <ids>](#api-key-revoke-ids) + - [api-key generate](#api-key-generate) + - [api-key revoke](#api-key-revoke) - [api-keys](#api-keys) - Apps - - [app create <name>](#app-create-name) + - [app create](#app-create) - Authentication @@ -178,82 +178,82 @@ are encouraged to regularly update the balena CLI to the latest version. - Blocks - - [block create <name>](#block-create-name) + - [block create](#block-create) - Config - [config generate](#config-generate) - - [config inject <file>](#config-inject-file) + - [config inject](#config-inject) - [config read](#config-read) - [config reconfigure](#config-reconfigure) - - [config write <key> <value>](#config-write-key-value) + - [config write](#config-write) - Deploy - - [build [source]](#build-source) - - [deploy <fleet> [image]](#deploy-fleet-image) + - [build](#build) + - [deploy](#deploy) - Devices - - [device deactivate <uuid>](#device-deactivate-uuid) - - [device identify <uuid>](#device-identify-uuid) - - [device <uuid>](#device-uuid) + - [device deactivate](#device-deactivate) + - [device identify](#device-identify) + - [device](#device) - [device init](#device-init) - - [device local-mode <uuid>](#device-local-mode-uuid) - - [device move <uuid(s)>](#device-move-uuid-s) - - [device os-update <uuid>](#device-os-update-uuid) - - [device pin <uuid> [releasetopinto]](#device-pin-uuid-releasetopinto) - - [device public-url <uuid>](#device-public-url-uuid) - - [device purge <uuid>](#device-purge-uuid) - - [device reboot <uuid>](#device-reboot-uuid) - - [device register <fleet>](#device-register-fleet) - - [device rename <uuid> [newname]](#device-rename-uuid-newname) - - [device restart <uuid>](#device-restart-uuid) - - [device rm <uuid(s)>](#device-rm-uuid-s) - - [device shutdown <uuid>](#device-shutdown-uuid) - - [device start-service <uuid>](#device-start-service-uuid) - - [device stop-service <uuid>](#device-stop-service-uuid) - - [device track-fleet <uuid>](#device-track-fleet-uuid) + - [device local-mode](#device-local-mode) + - [device move](#device-move) + - [device os-update](#device-os-update) + - [device pin](#device-pin) + - [device public-url](#device-public-url) + - [device purge](#device-purge) + - [device reboot](#device-reboot) + - [device register](#device-register) + - [device rename](#device-rename) + - [device restart](#device-restart) + - [device rm](#device-rm) + - [device shutdown](#device-shutdown) + - [device start-service](#device-start-service) + - [device stop-service](#device-stop-service) + - [device track-fleet](#device-track-fleet) - [devices](#devices) - [devices supported](#devices-supported) - Environment Variables + - [env add](#env-add) + - [env rename](#env-rename) + - [env rm](#env-rm) - [envs](#envs) - - [env rm <id>](#env-rm-id) - - [env add <name> [value]](#env-add-name-value) - - [env rename <id> <value>](#env-rename-id-value) - Fleets - - [fleet create <name>](#fleet-create-name) - - [fleet <fleet>](#fleet-fleet) - - [fleet pin <slug> [releasetopinto]](#fleet-pin-slug-releasetopinto) - - [fleet purge <fleet>](#fleet-purge-fleet) - - [fleet rename <fleet> [newname]](#fleet-rename-fleet-newname) - - [fleet restart <fleet>](#fleet-restart-fleet) - - [fleet rm <fleet>](#fleet-rm-fleet) - - [fleet track-latest <slug>](#fleet-track-latest-slug) + - [fleet create](#fleet-create) + - [fleet](#fleet) + - [fleet pin](#fleet-pin) + - [fleet purge](#fleet-purge) + - [fleet rename](#fleet-rename) + - [fleet restart](#fleet-restart) + - [fleet rm](#fleet-rm) + - [fleet track-latest](#fleet-track-latest) - [fleets](#fleets) - Local - - [local configure <target>](#local-configure-target) - - [local flash <image>](#local-flash-image) + - [local configure](#local-configure) + - [local flash](#local-flash) - Logs - - [logs <device>](#logs-device) + - [logs](#logs) - Network - [scan](#scan) - - [ssh <fleetordevice> [service]](#ssh-fleetordevice-service) - - [tunnel <deviceorfleet>](#tunnel-deviceorfleet) + - [ssh](#ssh) + - [tunnel](#tunnel) - Notes - - [note <|note>](#note-note) + - [notes](#notes) - Organizations @@ -261,32 +261,32 @@ are encouraged to regularly update the balena CLI to the latest version. - 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>](#os-configure-image) - - [os initialize <image>](#os-initialize-image) + - [os build-config](#os-build-config) + - [os configure](#os-configure) + - [os download](#os-download) + - [os initialize](#os-initialize) + - [os versions](#os-versions) - Platform - - [join [deviceiporhostname]](#join-deviceiporhostname) - - [leave [deviceiporhostname]](#leave-deviceiporhostname) + - [join](#join) + - [leave](#leave) - Preload - - [preload <image>](#preload-image) + - [preload](#preload) - Push - - [push <fleetordevice>](#push-fleetordevice) + - [push](#push) - Releases - - [release finalize <commitorid>](#release-finalize-commitorid) - - [release <commitorid>](#release-commitorid) - - [release invalidate <commitorid>](#release-invalidate-commitorid) - - [release validate <commitorid>](#release-validate-commitorid) - - [releases <fleet>](#releases-fleet) + - [release finalize](#release-finalize) + - [release](#release) + - [release invalidate](#release-invalidate) + - [release validate](#release-validate) + - [releases](#releases) - Settings @@ -294,19 +294,19 @@ are encouraged to regularly update the balena CLI to the latest version. - SSH Keys - - [key add <name> [path]](#key-add-name-path) - - [key <id>](#key-id) - - [key rm <id>](#key-rm-id) + - [key add](#key-add) + - [key](#key) + - [key rm](#key-rm) - [keys](#keys) - Support - - [support <action>](#support-action) + - [support](#support) - Tags - - [tag rm <tagkey>](#tag-rm-tagkey) - - [tag set <tagkey> [value]](#tag-set-tagkey-value) + - [tag rm](#tag-rm) + - [tag set](#tag-set) - [tags](#tags) - Utilities @@ -319,7 +319,7 @@ are encouraged to regularly update the balena CLI to the latest version. # API Keys -## api-key generate <name> +## api-key generate Generate a new balenaCloud API key for the current user, with the given name. The key will be logged to the console. @@ -339,7 +339,7 @@ the API key name ### Options -## api-key revoke <ids> +## api-key revoke Revoke balenaCloud API keys with the given comma-separated list of ids. @@ -381,7 +381,7 @@ fleet name or slug (preferred) # Apps -## app create <name> +## app create Create a new balena app. @@ -503,7 +503,7 @@ Examples: # Blocks -## block create <name> +## block create Create a new balena block. @@ -656,7 +656,7 @@ custom key name assigned to generated provisioning api key expiry date assigned to generated provisioning api key (format: YYYY-MM-DD) -## config inject <file> +## config inject Inject a 'config.json' file to a balenaOS image file or attached SD card or USB stick. @@ -736,7 +736,7 @@ show advanced commands balenaOS version, for example "2.32.0" or "2.44.0+rev1" -## config write <key> <value> +## config write Write a key-value pair to the 'config.json' file of a balenaOS image file or attached SD card or USB stick. @@ -768,7 +768,7 @@ path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2) # Deploy -## build [source] +## build Use this command to build an image or a complete multicontainer project with the provided docker daemon in your development machine or balena device. @@ -967,7 +967,7 @@ Docker host TLS certificate file Docker host TLS key file -## deploy <fleet> [image] +## deploy Usage: `deploy ([image] | --build [--source build-dir])` @@ -1194,7 +1194,7 @@ Docker host TLS key file # Devices -## device deactivate <uuid> +## device deactivate Deactivate a device. @@ -1218,7 +1218,7 @@ the UUID of the device to be deactivated answer "yes" to all questions (non interactive use) -## device identify <uuid> +## device identify Identify a device by making the ACT LED blink (Raspberry Pi). @@ -1234,7 +1234,7 @@ the uuid of the device to identify ### Options -## device <uuid> +## device Show information about a single device. @@ -1351,7 +1351,7 @@ custom key name assigned to generated provisioning api key expiry date assigned to generated provisioning api key (format: YYYY-MM-DD) -## device local-mode <uuid> +## device local-mode Output current local mode status, or enable/disable local mode for specified device. @@ -1383,7 +1383,7 @@ disable local mode output boolean indicating local mode status -## device move <uuid(s)> +## device move Move one or more devices to another fleet. @@ -1418,7 +1418,7 @@ comma-separated list (no blank spaces) of device UUIDs to be moved fleet name or slug (preferred) -## device os-update <uuid> +## device os-update Start a Host OS update for a device. @@ -1454,7 +1454,7 @@ include pre-release balenaOS versions answer "yes" to all questions (non interactive use) -## device pin <uuid> [releaseToPinTo] +## device pin Pin a device to a release. @@ -1477,7 +1477,7 @@ the commit of the release for the device to get pinned to ### Options -## device public-url <uuid> +## device public-url This command will output the current public URL for the specified device. It can also enable or disable the URL, @@ -1510,7 +1510,7 @@ disable the public URL determine if public URL is enabled -## device purge <uuid> +## device purge Purge data from a device. This will clear the device's "/data" directory. @@ -1531,7 +1531,7 @@ comma-separated list (no blank spaces) of device UUIDs ### Options -## device reboot <uuid> +## device reboot Remotely reboot a device. @@ -1551,7 +1551,7 @@ the uuid of the device to reboot force action if the update lock is set -## device register <fleet> +## device register Register a new device with a balena fleet. @@ -1590,7 +1590,7 @@ custom uuid device type slug (run 'balena devices supported' for possible values) -## device rename <uuid> [newName] +## device rename Rename a device. @@ -1613,7 +1613,7 @@ the new name for the device ### Options -## device restart <uuid> +## device restart Restart containers on a device. If the --service flag is provided, then only those services' containers @@ -1643,7 +1643,7 @@ comma-separated list (no blank spaces) of device UUIDs to restart comma-separated list (no blank spaces) of service names to restart -## device rm <uuid(s)> +## device rm Remove one or more devices from balena. @@ -1668,7 +1668,7 @@ comma-separated list (no blank spaces) of device UUIDs to be removed answer "yes" to all questions (non interactive use) -## device shutdown <uuid> +## device shutdown Remotely shutdown a device. @@ -1688,7 +1688,7 @@ the uuid of the device to shutdown force action if the update lock is set -## device start-service <uuid> +## device start-service Start containers on a device. @@ -1712,7 +1712,7 @@ comma-separated list (no blank spaces) of service names ### Options -## device stop-service <uuid> +## device stop-service Stop containers on a device. @@ -1736,7 +1736,7 @@ comma-separated list (no blank spaces) of service names ### Options -## device track-fleet <uuid> +## device track-fleet Make a device track the fleet's pinned release. @@ -1813,6 +1813,211 @@ produce JSON output instead of tabular output # Environment Variables +## env add + +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 +used alongside the --service option to define a service-specific variable. +(A service corresponds to a Docker image/container in a microservices fleet.) +When the --service option is used in conjunction with the --device option, +the service variable applies to the selected device only. Otherwise, it +applies to all devices of the selected fleet. If the --service option is +omitted, the variable applies to all services. + +If VALUE is omitted, the CLI will attempt to use the value of the environment +variable of same name in the CLI process' environment. In this case, a warning +message will be printed. Use `--quiet` to suppress it. + +'BALENA_' or 'RESIN_' are reserved variable name prefixes used to identify +"configuration variables". Configuration variables control balena platform +features and are treated specially by balenaOS and the balena supervisor +running on devices. They are also stored differently in the balenaCloud API +database. Configuration variables cannot be set for specific services, +therefore the --service option cannot be used when the variable name starts +with a reserved prefix. When defining custom fleet variables, please avoid +these reserved prefixes. + +Fleets may be specified by fleet name or slug. Fleet slugs are +the recommended option, as they are unique and unambiguous. Slugs can be +listed with the `balena fleets` command. Note that slugs may change if the +fleet is renamed. Fleet names are not unique and may result in "Fleet is +ambiguous" errors at any time (even if it "used to work in the past"), for +example if the name clashes with a newly created public fleet, or with fleets +from other balena accounts that you may be invited to join under any role. +For this reason, fleet names are especially discouraged in scripts (e.g. CI +environments). + +Examples: + + $ balena env add TERM --fleet MyFleet + $ balena env add EDITOR vim -f myorg/myfleet + $ balena env add EDITOR vim --fleet MyFleet,MyFleet2 + $ balena env add EDITOR vim --fleet MyFleet --service MyService + $ balena env add EDITOR vim --fleet MyFleet,MyFleet2 --service MyService,MyService2 + $ balena env add EDITOR vim --device 7cf02a6 + $ balena env add EDITOR vim --device 7cf02a6,d6f1433 + $ balena env add EDITOR vim --device 7cf02a6 --service MyService + $ balena env add EDITOR vim --device 7cf02a6,d6f1433 --service MyService,MyService2 + +### Arguments + +#### NAME + +environment or config variable name + +#### VALUE + +variable value; if omitted, use value from this process' environment + +### Options + +#### -f, --fleet FLEET + +fleet name or slug (preferred) + +#### -d, --device DEVICE + +device UUID + +#### -q, --quiet + +suppress warning messages + +#### -s, --service SERVICE + +service name + +## env rename + +Change the value of a configuration or environment variable for a fleet, +device or service, as selected by command-line options. + +Variables are selected by their database ID (as reported by the 'balena envs' +command) and one of six database "resource types": + +- fleet environment variable +- fleet configuration variable (--config) +- fleet service variable (--service) +- device environment variable (--device) +- device configuration variable (--device --config) +- device service variable (--device --service) + +The --device option selects a device-specific variable instead of a fleet +variable. + +The --config option selects a configuration variable. Configuration variable +names typically start with the 'BALENA_' or 'RESIN_' prefixes and are used to +configure balena platform features. + +The --service option selects a service variable, which is an environment variable +that applies to a specifc service (container) in a microservices (multicontainer) +fleet. + +The --service and --config options cannot be used together, but they can be +used alongside the --device option to select a device-specific service or +configuration variable. + +Examples: + + $ balena env rename 123123 emacs + $ balena env rename 234234 emacs --service + $ balena env rename 345345 emacs --device + $ balena env rename 456456 emacs --device --service + $ balena env rename 567567 1 --config + $ balena env rename 678678 1 --device --config + +### Arguments + +#### ID + +variable's numeric database ID + +#### VALUE + +variable value; if omitted, use value from this process' environment + +### Options + +#### -c, --config + +select a configuration variable (may be used together with the --device option) + +#### -d, --device + +select a device-specific variable instead of a fleet variable + +#### -s, --service + +select a service variable (may be used together with the --device option) + +## env rm + +Remove a configuration or environment variable from a fleet, device +or service, as selected by command-line options. + +Variables are selected by their database ID (as reported by the 'balena envs' +command) and one of six database "resource types": + +- fleet environment variable +- fleet configuration variable (--config) +- fleet service variable (--service) +- device environment variable (--device) +- device configuration variable (--device --config) +- device service variable (--device --service) + +The --device option selects a device-specific variable instead of a fleet +variable. + +The --config option selects a configuration variable. Configuration variable +names typically start with the 'BALENA_' or 'RESIN_' prefixes and are used to +configure balena platform features. + +The --service option selects a service variable, which is an environment variable +that applies to a specifc service (container) in a microservices (multicontainer) +fleet. + +The --service and --config options cannot be used together, but they can be +used alongside the --device option to select a device-specific service or +configuration variable. + +Interactive confirmation is normally asked before the variable is deleted. +The --yes option disables this behavior. + +Examples: + + $ balena env rm 123123 + $ balena env rm 234234 --yes + $ balena env rm 345345 --config + $ balena env rm 456456 --service + $ balena env rm 567567 --device + $ balena env rm 678678 --device --config + $ balena env rm 789789 --device --service --yes + +### Arguments + +#### ID + +variable's numeric database ID + +### Options + +#### -c, --config + +select a configuration variable (may be used together with the --device option) + +#### -d, --device + +select a device-specific variable instead of a fleet variable + +#### -s, --service + +select a service variable (may be used together with the --device option) + +#### -y, --yes + +do not prompt for confirmation before deleting the variable + ## envs List the environment or configuration variables of a fleet, device or @@ -1888,214 +2093,9 @@ produce JSON output instead of tabular output service name -## env rm <id> - -Remove a configuration or environment variable from a fleet, device -or service, as selected by command-line options. - -Variables are selected by their database ID (as reported by the 'balena envs' -command) and one of six database "resource types": - -- fleet environment variable -- fleet configuration variable (--config) -- fleet service variable (--service) -- device environment variable (--device) -- device configuration variable (--device --config) -- device service variable (--device --service) - -The --device option selects a device-specific variable instead of a fleet -variable. - -The --config option selects a configuration variable. Configuration variable -names typically start with the 'BALENA_' or 'RESIN_' prefixes and are used to -configure balena platform features. - -The --service option selects a service variable, which is an environment variable -that applies to a specifc service (container) in a microservices (multicontainer) -fleet. - -The --service and --config options cannot be used together, but they can be -used alongside the --device option to select a device-specific service or -configuration variable. - -Interactive confirmation is normally asked before the variable is deleted. -The --yes option disables this behavior. - -Examples: - - $ balena env rm 123123 - $ balena env rm 234234 --yes - $ balena env rm 345345 --config - $ balena env rm 456456 --service - $ balena env rm 567567 --device - $ balena env rm 678678 --device --config - $ balena env rm 789789 --device --service --yes - -### Arguments - -#### ID - -variable's numeric database ID - -### Options - -#### -c, --config - -select a configuration variable (may be used together with the --device option) - -#### -d, --device - -select a device-specific variable instead of a fleet variable - -#### -s, --service - -select a service variable (may be used together with the --device option) - -#### -y, --yes - -do not prompt for confirmation before deleting the variable - -## env add <name> [value] - -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 -used alongside the --service option to define a service-specific variable. -(A service corresponds to a Docker image/container in a microservices fleet.) -When the --service option is used in conjunction with the --device option, -the service variable applies to the selected device only. Otherwise, it -applies to all devices of the selected fleet. If the --service option is -omitted, the variable applies to all services. - -If VALUE is omitted, the CLI will attempt to use the value of the environment -variable of same name in the CLI process' environment. In this case, a warning -message will be printed. Use `--quiet` to suppress it. - -'BALENA_' or 'RESIN_' are reserved variable name prefixes used to identify -"configuration variables". Configuration variables control balena platform -features and are treated specially by balenaOS and the balena supervisor -running on devices. They are also stored differently in the balenaCloud API -database. Configuration variables cannot be set for specific services, -therefore the --service option cannot be used when the variable name starts -with a reserved prefix. When defining custom fleet variables, please avoid -these reserved prefixes. - -Fleets may be specified by fleet name or slug. Fleet slugs are -the recommended option, as they are unique and unambiguous. Slugs can be -listed with the `balena fleets` command. Note that slugs may change if the -fleet is renamed. Fleet names are not unique and may result in "Fleet is -ambiguous" errors at any time (even if it "used to work in the past"), for -example if the name clashes with a newly created public fleet, or with fleets -from other balena accounts that you may be invited to join under any role. -For this reason, fleet names are especially discouraged in scripts (e.g. CI -environments). - -Examples: - - $ balena env add TERM --fleet MyFleet - $ balena env add EDITOR vim -f myorg/myfleet - $ balena env add EDITOR vim --fleet MyFleet,MyFleet2 - $ balena env add EDITOR vim --fleet MyFleet --service MyService - $ balena env add EDITOR vim --fleet MyFleet,MyFleet2 --service MyService,MyService2 - $ balena env add EDITOR vim --device 7cf02a6 - $ balena env add EDITOR vim --device 7cf02a6,d6f1433 - $ balena env add EDITOR vim --device 7cf02a6 --service MyService - $ balena env add EDITOR vim --device 7cf02a6,d6f1433 --service MyService,MyService2 - -### Arguments - -#### NAME - -environment or config variable name - -#### VALUE - -variable value; if omitted, use value from this process' environment - -### Options - -#### -f, --fleet FLEET - -fleet name or slug (preferred) - -#### -d, --device DEVICE - -device UUID - -#### -q, --quiet - -suppress warning messages - -#### -s, --service SERVICE - -service name - -## env rename <id> <value> - -Change the value of a configuration or environment variable for a fleet, -device or service, as selected by command-line options. - -Variables are selected by their database ID (as reported by the 'balena envs' -command) and one of six database "resource types": - -- fleet environment variable -- fleet configuration variable (--config) -- fleet service variable (--service) -- device environment variable (--device) -- device configuration variable (--device --config) -- device service variable (--device --service) - -The --device option selects a device-specific variable instead of a fleet -variable. - -The --config option selects a configuration variable. Configuration variable -names typically start with the 'BALENA_' or 'RESIN_' prefixes and are used to -configure balena platform features. - -The --service option selects a service variable, which is an environment variable -that applies to a specifc service (container) in a microservices (multicontainer) -fleet. - -The --service and --config options cannot be used together, but they can be -used alongside the --device option to select a device-specific service or -configuration variable. - -Examples: - - $ balena env rename 123123 emacs - $ balena env rename 234234 emacs --service - $ balena env rename 345345 emacs --device - $ balena env rename 456456 emacs --device --service - $ balena env rename 567567 1 --config - $ balena env rename 678678 1 --device --config - -### Arguments - -#### ID - -variable's numeric database ID - -#### VALUE - -variable value; if omitted, use value from this process' environment - -### Options - -#### -c, --config - -select a configuration variable (may be used together with the --device option) - -#### -d, --device - -select a device-specific variable instead of a fleet variable - -#### -s, --service - -select a service variable (may be used together with the --device option) - # Fleets -## fleet create <name> +## fleet create Create a new balena fleet. @@ -2136,7 +2136,7 @@ handle of the organization the fleet should belong to fleet device type (Check available types with `balena devices supported`) -## fleet <fleet> +## fleet Display detailed information about a single fleet. @@ -2172,7 +2172,7 @@ open fleet dashboard page produce JSON output instead of tabular output -## fleet pin <slug> [releaseToPinTo] +## fleet pin Pin a fleet to a release. @@ -2195,7 +2195,7 @@ the commit of the release for the fleet to get pinned to ### Options -## fleet purge <fleet> +## fleet purge Purge data from all devices belonging to a fleet. This will clear the fleet's '/data' directory. @@ -2223,7 +2223,7 @@ fleet name or slug (preferred) ### Options -## fleet rename <fleet> [newName] +## fleet rename Rename a fleet. @@ -2258,7 +2258,7 @@ the new name for the fleet ### Options -## fleet restart <fleet> +## fleet restart Restart all devices belonging to a fleet. @@ -2285,7 +2285,7 @@ fleet name or slug (preferred) ### Options -## fleet rm <fleet> +## fleet rm Permanently remove a fleet. @@ -2319,7 +2319,7 @@ fleet name or slug (preferred) answer "yes" to all questions (non interactive use) -## fleet track-latest <slug> +## fleet track-latest Make this fleet track the latest release. @@ -2355,7 +2355,7 @@ produce JSON output instead of tabular output # Local -## local configure <target> +## local configure Configure or reconfigure a balenaOS drive or image. @@ -2372,7 +2372,7 @@ path of drive or image to configure ### Options -## local flash <image> +## local flash Flash a balenaOS image to a drive. Image file may be one of: .img|.zip|.gz|.bz2|.xz @@ -2406,7 +2406,7 @@ answer "yes" to all questions (non interactive use) # Logs -## logs <device> +## logs Show logs for a specific device. @@ -2492,7 +2492,7 @@ scan timeout in seconds produce JSON output instead of tabular output -## ssh <fleetOrDevice> [service] +## ssh 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. @@ -2557,7 +2557,7 @@ increase verbosity bypass global proxy configuration for the ssh connection -## tunnel <deviceOrFleet> +## tunnel Use this command to open local TCP ports that tunnel to listening sockets in a balenaOS device. @@ -2610,7 +2610,7 @@ port mapping in the format [:[localIP:]localPort] # Notes -## note <|note> +## notes Set or update a device note. If the note argument is not provided, it will be read from stdin. @@ -2652,90 +2652,7 @@ Examples: # OS -## os versions <type> - -Show the available balenaOS versions for the given device type. -Check available types with `balena devices supported`. - -balenaOS ESR versions can be listed with the '--esr' option. See also: -https://www.balena.io/docs/reference/OS/extended-support-release/ - -Examples: - - $ balena os versions raspberrypi3 - -### Arguments - -#### TYPE - -device type - -### Options - -#### --esr - -select balenaOS ESR versions - -#### --include-draft - -include pre-release balenaOS versions - -## os download <type> - -Download an unconfigured OS image for the specified device type. -Check available device types with 'balena devices supported'. - -Note: Currently this command only works with balenaCloud, not openBalena. -If using openBalena, please download the OS from: https://www.balena.io/os/ - -The '--version' option is used to select the balenaOS version. If omitted, -the latest released version is downloaded (and if only pre-release versions -exist, the latest pre-release version is downloaded). - -Use '--version menu' or '--version menu-esr' to interactively select the -OS version. The latter lists ESR versions which are only available for -download on Production and Enterprise plans. See also: -https://www.balena.io/docs/reference/OS/extended-support-release/ - -Development images can be selected by appending `.dev` to the version. - -Examples: - - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.101.7 - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2022.7.0 - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version ^2.90.0 - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.60.1+rev1 - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.60.1+rev1.dev - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2021.10.2.prod - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version latest - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version default - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu - $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu-esr - -### Arguments - -#### TYPE - -the device type - -### Options - -#### -o, --output OUTPUT - -output path - -#### --version VERSION - -version number (ESR or non-ESR versions), -or semver range (non-ESR versions only), -or 'latest' (includes pre-releases), -or 'default' (excludes pre-releases if at least one released version is available), -or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available), -or 'menu' (interactive menu, non-ESR versions), -or 'menu-esr' (interactive menu, ESR versions) - -## os build-config <image> <device-type> +## os build-config Interactively generate a configuration file that can then be used as non-interactive input by the 'balena os configure' command. @@ -2765,7 +2682,7 @@ show advanced configuration options path to output JSON file -## os configure <image> +## os configure Configure a previously downloaded balenaOS image for a specific device type or fleet. @@ -2890,7 +2807,62 @@ custom key name assigned to generated provisioning api key expiry date assigned to generated provisioning api key (format: YYYY-MM-DD) -## os initialize <image> +## os download + +Download an unconfigured OS image for the specified device type. +Check available device types with 'balena devices supported'. + +Note: Currently this command only works with balenaCloud, not openBalena. +If using openBalena, please download the OS from: https://www.balena.io/os/ + +The '--version' option is used to select the balenaOS version. If omitted, +the latest released version is downloaded (and if only pre-release versions +exist, the latest pre-release version is downloaded). + +Use '--version menu' or '--version menu-esr' to interactively select the +OS version. The latter lists ESR versions which are only available for +download on Production and Enterprise plans. See also: +https://www.balena.io/docs/reference/OS/extended-support-release/ + +Development images can be selected by appending `.dev` to the version. + +Examples: + + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.101.7 + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2022.7.0 + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version ^2.90.0 + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.60.1+rev1 + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.60.1+rev1.dev + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2021.10.2.prod + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version latest + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version default + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu + $ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu-esr + +### Arguments + +#### TYPE + +the device type + +### Options + +#### -o, --output OUTPUT + +output path + +#### --version VERSION + +version number (ESR or non-ESR versions), +or semver range (non-ESR versions only), +or 'latest' (includes pre-releases), +or 'default' (excludes pre-releases if at least one released version is available), +or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available), +or 'menu' (interactive menu, non-ESR versions), +or 'menu-esr' (interactive menu, ESR versions) + +## os initialize Initialize an os image for a device with a previously configured operating system image and flash the @@ -2927,9 +2899,37 @@ Check `balena util available-drives` for available options. answer "yes" to all questions (non interactive use) +## os versions + +Show the available balenaOS versions for the given device type. +Check available types with `balena devices supported`. + +balenaOS ESR versions can be listed with the '--esr' option. See also: +https://www.balena.io/docs/reference/OS/extended-support-release/ + +Examples: + + $ balena os versions raspberrypi3 + +### Arguments + +#### TYPE + +device type + +### Options + +#### --esr + +select balenaOS ESR versions + +#### --include-draft + +include pre-release balenaOS versions + # Platform -## join [deviceIpOrHostname] +## join 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. @@ -2981,7 +2981,7 @@ fleet name or slug (preferred) the interval in minutes to check for updates -## leave [deviceIpOrHostname] +## leave Remove a local device from its balena fleet, causing the device to "leave" the server it is provisioned on. This effectively makes the device @@ -3010,7 +3010,7 @@ the device IP or hostname # Preload -## preload <image> +## preload Preload a release (service images/containers) from a balena fleet, and optionally a balenaOS splash screen, in a previously downloaded '.img' balenaOS image file @@ -3118,7 +3118,7 @@ Docker host TLS key file # Push -## push <fleetOrDevice> +## push Build release images on balenaCloud servers or on a local mode device. @@ -3345,7 +3345,7 @@ The notes for this release # Releases -## release finalize <commitOrId> +## release finalize 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 @@ -3371,7 +3371,7 @@ the commit or ID of the release to finalize ### Options -## release <commitOrId> +## release 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 @@ -3401,7 +3401,7 @@ produce JSON output instead of tabular output Return the release composition -## release invalidate <commitOrId> +## release invalidate Invalidate a release. @@ -3422,7 +3422,7 @@ the commit or ID of the release to invalidate ### Options -## release validate <commitOrId> +## release validate Validate a release. @@ -3442,7 +3442,7 @@ the commit or ID of the release to validate ### Options -## releases <fleet> +## releases List all releases of the given fleet. @@ -3492,13 +3492,13 @@ Examples: # SSH Keys -## key add <name> [path] +## key add 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. -About SSH keys +About SSH keys 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 @@ -3531,7 +3531,7 @@ the path to the public key file ### Options -## key <id> +## key Display a single SSH key registered in balenaCloud for the logged in user. @@ -3547,7 +3547,7 @@ balenaCloud ID for the SSH key ### Options -## key rm <id> +## key rm Remove a single SSH key registered in balenaCloud for the logged in user. @@ -3582,7 +3582,7 @@ Examples: # Support -## support <action> +## support Grant or revoke balena support agent access to devices or fleets on balenaCloud. (This command does not apply to openBalena.) @@ -3632,7 +3632,7 @@ length of time to enable support for, in (h)ours or (d)ays, e.g. 12h, 2d # Tags -## tag rm <tagKey> +## tag rm Remove a tag from a fleet, device or release. @@ -3674,7 +3674,7 @@ device UUID release id -## tag set <tagKey> [value] +## tag set Set a tag on a fleet, device or release. diff --git a/src/commands/api-key/generate.ts b/src/commands/api-key/generate.ts index c9213b67..58cd0608 100644 --- a/src/commands/api-key/generate.ts +++ b/src/commands/api-key/generate.ts @@ -40,8 +40,6 @@ export default class GenerateCmd extends Command { }), }; - public static usage = 'api-key generate '; - public static flags = { help: cf.help, }; diff --git a/src/commands/api-key/revoke.ts b/src/commands/api-key/revoke.ts index 27475f39..2b158e7a 100644 --- a/src/commands/api-key/revoke.ts +++ b/src/commands/api-key/revoke.ts @@ -41,8 +41,6 @@ export default class RevokeCmd extends Command { }), }; - public static usage = 'api-key revoke '; - public static flags = { help: cf.help, }; diff --git a/src/commands/api-keys/index.ts b/src/commands/api-keys/index.ts index cadf144e..498ceaf6 100644 --- a/src/commands/api-keys/index.ts +++ b/src/commands/api-keys/index.ts @@ -30,8 +30,6 @@ export default class ApiKeysCmd extends Command { `; public static examples = ['$ balena api-keys']; - public static usage = 'api-keys'; - public static flags = { help: cf.help, user: Flags.boolean({ diff --git a/src/commands/app/create.ts b/src/commands/app/create.ts index 5d82e33c..5f333a92 100644 --- a/src/commands/app/create.ts +++ b/src/commands/app/create.ts @@ -56,8 +56,6 @@ export default class AppCreateCmd extends Command { }), }; - public static usage = 'app create '; - public static flags = { organization: Flags.string({ char: 'o', diff --git a/src/commands/block/create.ts b/src/commands/block/create.ts index efb5ced7..47ce1959 100644 --- a/src/commands/block/create.ts +++ b/src/commands/block/create.ts @@ -56,8 +56,6 @@ export default class BlockCreateCmd extends Command { }), }; - public static usage = 'block create '; - public static flags = { organization: Flags.string({ char: 'o', diff --git a/src/commands/build/index.ts b/src/commands/build/index.ts index 906f3489..08db04af 100644 --- a/src/commands/build/index.ts +++ b/src/commands/build/index.ts @@ -84,8 +84,6 @@ ${dockerignoreHelp} source: Args.string({ description: 'path of project source directory' }), }; - public static usage = 'build [source]'; - public static flags = { arch: Flags.string({ description: 'the architecture to build for', diff --git a/src/commands/config/generate.ts b/src/commands/config/generate.ts index 2788b3c6..25f7d7cd 100644 --- a/src/commands/config/generate.ts +++ b/src/commands/config/generate.ts @@ -60,8 +60,6 @@ export default class ConfigGenerateCmd extends Command { '$ balena config generate --fleet myorg/fleet --version 2.12.7 --network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 15', ]; - public static usage = 'config generate'; - public static flags = { version: Flags.string({ description: 'a balenaOS version', diff --git a/src/commands/config/inject.ts b/src/commands/config/inject.ts index 6e344f70..9640776e 100644 --- a/src/commands/config/inject.ts +++ b/src/commands/config/inject.ts @@ -43,8 +43,6 @@ export default class ConfigInjectCmd extends Command { }), }; - public static usage = 'config inject '; - public static flags = { drive: cf.driveOrImg, help: cf.help, diff --git a/src/commands/config/read.ts b/src/commands/config/read.ts index 333fea87..32fdf9ee 100644 --- a/src/commands/config/read.ts +++ b/src/commands/config/read.ts @@ -36,8 +36,6 @@ export default class ConfigReadCmd extends Command { '$ balena config read --drive balena.img', ]; - public static usage = 'config read'; - public static flags = { drive: cf.driveOrImg, help: cf.help, diff --git a/src/commands/config/reconfigure.ts b/src/commands/config/reconfigure.ts index be9ab466..d00e7005 100644 --- a/src/commands/config/reconfigure.ts +++ b/src/commands/config/reconfigure.ts @@ -39,8 +39,6 @@ export default class ConfigReconfigureCmd extends Command { '$ balena config reconfigure --drive balena.img --advanced', ]; - public static usage = 'config reconfigure'; - public static flags = { drive: cf.driveOrImg, advanced: Flags.boolean({ diff --git a/src/commands/config/write.ts b/src/commands/config/write.ts index e1323f5f..8147169f 100644 --- a/src/commands/config/write.ts +++ b/src/commands/config/write.ts @@ -48,8 +48,6 @@ export default class ConfigWriteCmd extends Command { }), }; - public static usage = 'config write '; - public static flags = { drive: cf.driveOrImg, help: cf.help, diff --git a/src/commands/deploy/index.ts b/src/commands/deploy/index.ts index 1fa0232c..cf00b220 100644 --- a/src/commands/deploy/index.ts +++ b/src/commands/deploy/index.ts @@ -108,8 +108,6 @@ ${dockerignoreHelp} image: Args.string({ description: 'the image to deploy' }), }; - public static usage = 'deploy [image]'; - public static flags = { source: Flags.string({ description: diff --git a/src/commands/device/deactivate.ts b/src/commands/device/deactivate.ts index 43afcc8e..52c9ff8c 100644 --- a/src/commands/device/deactivate.ts +++ b/src/commands/device/deactivate.ts @@ -41,8 +41,6 @@ export default class DeviceDeactivateCmd extends Command { }), }; - public static usage = 'device deactivate '; - public static flags = { yes: cf.yes, help: cf.help, diff --git a/src/commands/device/identify.ts b/src/commands/device/identify.ts index 7766a088..93b7e74d 100644 --- a/src/commands/device/identify.ts +++ b/src/commands/device/identify.ts @@ -36,8 +36,6 @@ export default class DeviceIdentifyCmd extends Command { }), }; - public static usage = 'device identify '; - public static flags = { help: cf.help, }; diff --git a/src/commands/device/index.ts b/src/commands/device/index.ts index 71dbef74..a9428c64 100644 --- a/src/commands/device/index.ts +++ b/src/commands/device/index.ts @@ -62,8 +62,6 @@ export default class DeviceCmd extends Command { }), }; - public static usage = 'device '; - public static flags = { json: cf.json, help: cf.help, diff --git a/src/commands/device/init.ts b/src/commands/device/init.ts index 3fc45e4b..41edcb04 100644 --- a/src/commands/device/init.ts +++ b/src/commands/device/init.ts @@ -74,8 +74,6 @@ export default class DeviceInitCmd extends Command { '$ balena device init --fleet myFleet --os-version 2.83.21+rev1.prod --drive /dev/disk5 --config config.json --yes', ]; - public static usage = 'device init'; - public static flags = { fleet: cf.fleet, yes: cf.yes, diff --git a/src/commands/device/local-mode.ts b/src/commands/device/local-mode.ts index 1d048baf..aa7be85a 100644 --- a/src/commands/device/local-mode.ts +++ b/src/commands/device/local-mode.ts @@ -42,8 +42,6 @@ export default class DeviceLocalModeCmd extends Command { }), }; - public static usage = 'device local-mode '; - public static flags = { enable: Flags.boolean({ description: 'enable local mode', diff --git a/src/commands/device/move.ts b/src/commands/device/move.ts index 20e4c9af..59fbd63f 100644 --- a/src/commands/device/move.ts +++ b/src/commands/device/move.ts @@ -54,8 +54,6 @@ export default class DeviceMoveCmd extends Command { }), }; - public static usage = 'device move '; - public static flags = { fleet: cf.fleet, help: cf.help, diff --git a/src/commands/device/os-update.ts b/src/commands/device/os-update.ts index bb5b3226..e335d151 100644 --- a/src/commands/device/os-update.ts +++ b/src/commands/device/os-update.ts @@ -47,8 +47,6 @@ export default class DeviceOsUpdateCmd extends Command { }), }; - public static usage = 'device os-update '; - public static flags = { version: Flags.string({ description: 'a balenaOS version', diff --git a/src/commands/device/pin.ts b/src/commands/device/pin.ts index 51f582bf..e27b294b 100644 --- a/src/commands/device/pin.ts +++ b/src/commands/device/pin.ts @@ -44,8 +44,6 @@ export default class DevicePinCmd extends Command { }), }; - public static usage = 'device pin [releaseToPinTo]'; - public static flags = { help: cf.help, }; diff --git a/src/commands/device/public-url.ts b/src/commands/device/public-url.ts index 51326070..91fd9314 100644 --- a/src/commands/device/public-url.ts +++ b/src/commands/device/public-url.ts @@ -44,8 +44,6 @@ export default class DevicePublicUrlCmd extends Command { }), }; - public static usage = 'device public-url '; - public static flags = { enable: Flags.boolean({ description: 'enable the public URL', diff --git a/src/commands/device/purge.ts b/src/commands/device/purge.ts index a40d00e6..7c548406 100644 --- a/src/commands/device/purge.ts +++ b/src/commands/device/purge.ts @@ -35,8 +35,6 @@ export default class DevicePurgeCmd extends Command { '$ balena device purge 55d43b3,23c73a1', ]; - public static usage = 'device purge '; - public static args = { uuid: Args.string({ description: 'comma-separated list (no blank spaces) of device UUIDs', diff --git a/src/commands/device/reboot.ts b/src/commands/device/reboot.ts index daef864b..1c4e5231 100644 --- a/src/commands/device/reboot.ts +++ b/src/commands/device/reboot.ts @@ -35,8 +35,6 @@ export default class DeviceRebootCmd extends Command { }), }; - public static usage = 'device reboot '; - public static flags = { force: cf.force, help: cf.help, diff --git a/src/commands/device/register.ts b/src/commands/device/register.ts index 7a9d10b5..6bfe5829 100644 --- a/src/commands/device/register.ts +++ b/src/commands/device/register.ts @@ -44,8 +44,6 @@ export default class DeviceRegisterCmd extends Command { fleet: ca.fleetRequired, }; - public static usage = 'device register '; - public static flags = { uuid: Flags.string({ description: 'custom uuid', diff --git a/src/commands/device/rename.ts b/src/commands/device/rename.ts index be6c38f4..9f0b12cf 100644 --- a/src/commands/device/rename.ts +++ b/src/commands/device/rename.ts @@ -43,8 +43,6 @@ export default class DeviceRenameCmd extends Command { }), }; - public static usage = 'device rename [newName]'; - public static flags = { help: cf.help, }; diff --git a/src/commands/device/restart.ts b/src/commands/device/restart.ts index 71f35f7b..b5fb5eef 100644 --- a/src/commands/device/restart.ts +++ b/src/commands/device/restart.ts @@ -53,8 +53,6 @@ export default class DeviceRestartCmd extends Command { }), }; - public static usage = 'device restart '; - public static flags = { service: Flags.string({ description: diff --git a/src/commands/device/rm.ts b/src/commands/device/rm.ts index 6f3cc482..e7cb221d 100644 --- a/src/commands/device/rm.ts +++ b/src/commands/device/rm.ts @@ -43,8 +43,6 @@ export default class DeviceRmCmd extends Command { }), }; - public static usage = 'device rm '; - public static flags = { yes: cf.yes, help: cf.help, diff --git a/src/commands/device/shutdown.ts b/src/commands/device/shutdown.ts index 7da13ade..8b9eeef6 100644 --- a/src/commands/device/shutdown.ts +++ b/src/commands/device/shutdown.ts @@ -36,8 +36,6 @@ export default class DeviceShutdownCmd extends Command { }), }; - public static usage = 'device shutdown '; - public static flags = { force: cf.force, help: cf.help, diff --git a/src/commands/device/start-service.ts b/src/commands/device/start-service.ts index 4637f221..27c80727 100644 --- a/src/commands/device/start-service.ts +++ b/src/commands/device/start-service.ts @@ -46,8 +46,6 @@ export default class DeviceStartServiceCmd extends Command { }), }; - public static usage = 'device start-service '; - public static flags = { help: cf.help, }; diff --git a/src/commands/device/stop-service.ts b/src/commands/device/stop-service.ts index b7aa53dc..e7900b6a 100644 --- a/src/commands/device/stop-service.ts +++ b/src/commands/device/stop-service.ts @@ -46,8 +46,6 @@ export default class DeviceStopServiceCmd extends Command { }), }; - public static usage = 'device stop-service '; - public static flags = { help: cf.help, }; diff --git a/src/commands/device/track-fleet.ts b/src/commands/device/track-fleet.ts index edb164ef..e5f35a32 100644 --- a/src/commands/device/track-fleet.ts +++ b/src/commands/device/track-fleet.ts @@ -35,8 +35,6 @@ export default class DeviceTrackFleetCmd extends Command { }), }; - public static usage = 'device track-fleet '; - public static flags = { help: cf.help, }; diff --git a/src/commands/devices/index.ts b/src/commands/devices/index.ts index e7196c42..c2a46b24 100644 --- a/src/commands/devices/index.ts +++ b/src/commands/devices/index.ts @@ -53,8 +53,6 @@ export default class DevicesCmd extends Command { '$ balena devices -f myorg/myfleet', ]; - public static usage = 'devices'; - public static flags = { fleet: cf.fleet, json: cf.json, diff --git a/src/commands/devices/supported.ts b/src/commands/devices/supported.ts index 93305a41..9a96f427 100644 --- a/src/commands/devices/supported.ts +++ b/src/commands/devices/supported.ts @@ -21,7 +21,6 @@ import Command from '../../command'; import * as cf from '../../utils/common-flags'; import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy'; -import { CommandHelp } from '../../utils/oclif-utils'; export default class DevicesSupportedCmd extends Command { public static description = stripIndent` @@ -40,11 +39,6 @@ export default class DevicesSupportedCmd extends Command { '$ balena devices supported --json', ]; - public static usage = ( - 'devices supported ' + - new CommandHelp({ args: DevicesSupportedCmd.args }).defaultUsage() - ).trim(); - public static flags = { help: cf.help, json: Flags.boolean({ diff --git a/src/commands/env/add.ts b/src/commands/env/add.ts index 479e03c4..fc99a309 100644 --- a/src/commands/env/add.ts +++ b/src/commands/env/add.ts @@ -92,7 +92,6 @@ export default class EnvAddCmd extends Command { // Required for supporting empty string ('') `value` args. public static strict = false; - public static usage = 'env add [value]'; public static flags = { fleet: { ...cf.fleet, exclusive: ['device'] }, diff --git a/src/commands/env/rename.ts b/src/commands/env/rename.ts index 6f9a3b99..11ae1ea0 100644 --- a/src/commands/env/rename.ts +++ b/src/commands/env/rename.ts @@ -53,8 +53,6 @@ export default class EnvRenameCmd extends Command { }), }; - public static usage = 'env rename '; - public static flags = { config: ec.booleanConfig, device: ec.booleanDevice, diff --git a/src/commands/env/rm.ts b/src/commands/env/rm.ts index d3589001..39538d55 100644 --- a/src/commands/env/rm.ts +++ b/src/commands/env/rm.ts @@ -52,8 +52,6 @@ export default class EnvRmCmd extends Command { }), }; - public static usage = 'env rm '; - public static flags = { config: ec.booleanConfig, device: ec.booleanDevice, diff --git a/src/commands/envs/index.ts b/src/commands/envs/index.ts index 310d9cca..553189d3 100644 --- a/src/commands/envs/index.ts +++ b/src/commands/envs/index.ts @@ -94,8 +94,6 @@ export default class EnvsCmd extends Command { '$ balena envs --device 7cf02a6 --service MyService', ]; - public static usage = 'envs'; - public static flags = { fleet: { ...cf.fleet, exclusive: ['device'] }, config: Flags.boolean({ diff --git a/src/commands/fleet/create.ts b/src/commands/fleet/create.ts index 2d10c221..46e958ad 100644 --- a/src/commands/fleet/create.ts +++ b/src/commands/fleet/create.ts @@ -56,8 +56,6 @@ export default class FleetCreateCmd extends Command { }), }; - public static usage = 'fleet create '; - public static flags = { organization: Flags.string({ char: 'o', diff --git a/src/commands/fleet/index.ts b/src/commands/fleet/index.ts index b34be44b..7c382550 100644 --- a/src/commands/fleet/index.ts +++ b/src/commands/fleet/index.ts @@ -41,8 +41,6 @@ export default class FleetCmd extends Command { fleet: ca.fleetRequired, }; - public static usage = 'fleet '; - public static flags = { help: cf.help, view: Flags.boolean({ diff --git a/src/commands/fleet/pin.ts b/src/commands/fleet/pin.ts index 2b9f6cc1..bcbfdc8a 100644 --- a/src/commands/fleet/pin.ts +++ b/src/commands/fleet/pin.ts @@ -44,8 +44,6 @@ export default class FleetPinCmd extends Command { }), }; - public static usage = 'fleet pin [releaseToPinTo]'; - public static flags = { help: cf.help, }; diff --git a/src/commands/fleet/purge.ts b/src/commands/fleet/purge.ts index 5456ea0a..386d0aab 100644 --- a/src/commands/fleet/purge.ts +++ b/src/commands/fleet/purge.ts @@ -40,8 +40,6 @@ export default class FleetPurgeCmd extends Command { fleet: ca.fleetRequired, }; - public static usage = 'fleet purge '; - public static flags = { help: cf.help, }; diff --git a/src/commands/fleet/rename.ts b/src/commands/fleet/rename.ts index 9214d2e6..a2b09196 100644 --- a/src/commands/fleet/rename.ts +++ b/src/commands/fleet/rename.ts @@ -48,8 +48,6 @@ export default class FleetRenameCmd extends Command { }), }; - public static usage = 'fleet rename [newName]'; - public static flags = { help: cf.help, }; diff --git a/src/commands/fleet/restart.ts b/src/commands/fleet/restart.ts index f9a8c4b6..83d560c6 100644 --- a/src/commands/fleet/restart.ts +++ b/src/commands/fleet/restart.ts @@ -39,8 +39,6 @@ export default class FleetRestartCmd extends Command { fleet: ca.fleetRequired, }; - public static usage = 'fleet restart '; - public static flags = { help: cf.help, }; diff --git a/src/commands/fleet/rm.ts b/src/commands/fleet/rm.ts index e75d1c04..e81168b2 100644 --- a/src/commands/fleet/rm.ts +++ b/src/commands/fleet/rm.ts @@ -42,8 +42,6 @@ export default class FleetRmCmd extends Command { fleet: ca.fleetRequired, }; - public static usage = 'fleet rm '; - public static flags = { yes: cf.yes, help: cf.help, diff --git a/src/commands/fleet/track-latest.ts b/src/commands/fleet/track-latest.ts index e05a9365..75fee330 100644 --- a/src/commands/fleet/track-latest.ts +++ b/src/commands/fleet/track-latest.ts @@ -38,8 +38,6 @@ export default class FleetTrackLatestCmd extends Command { }), }; - public static usage = 'fleet track-latest '; - public static flags = { help: cf.help, }; diff --git a/src/commands/fleets/index.ts b/src/commands/fleets/index.ts index e3980b08..91b2fba6 100644 --- a/src/commands/fleets/index.ts +++ b/src/commands/fleets/index.ts @@ -39,8 +39,6 @@ export default class FleetsCmd extends Command { public static examples = ['$ balena fleets']; - public static usage = 'fleets'; - public static flags = { help: cf.help, json: cf.json, diff --git a/src/commands/internal/osinit.ts b/src/commands/internal/osinit.ts index 8bc12992..dfc9bc9a 100644 --- a/src/commands/internal/osinit.ts +++ b/src/commands/internal/osinit.ts @@ -18,7 +18,6 @@ import { Args } from '@oclif/core'; import Command from '../../command'; import { stripIndent } from '../../utils/lazy'; -import { CommandHelp } from '../../utils/oclif-utils'; // 'Internal' commands are called during the execution of other commands. // `osinit` is called during `os initialize` @@ -48,11 +47,6 @@ export default class OsinitCmd extends Command { }), }; - public static usage = ( - 'internal osinit ' + - new CommandHelp({ args: OsinitCmd.args }).defaultUsage() - ).trim(); - public static hidden = true; public static root = true; public static offlineCompatible = true; diff --git a/src/commands/join/index.ts b/src/commands/join/index.ts index 152381b3..af09affc 100644 --- a/src/commands/join/index.ts +++ b/src/commands/join/index.ts @@ -60,9 +60,6 @@ export default class JoinCmd extends Command { }), }; - // Hardcoded to preserve camelcase - public static usage = 'join [deviceIpOrHostname]'; - public static flags = { fleet: cf.fleet, pollInterval: Flags.integer({ diff --git a/src/commands/key/add.ts b/src/commands/key/add.ts index 797c251b..24e4d4fb 100644 --- a/src/commands/key/add.ts +++ b/src/commands/key/add.ts @@ -29,7 +29,7 @@ export default class KeyAddCmd extends Command { If \`path\` is omitted, the command will attempt to read the SSH key from stdin. - About SSH keys + About SSH keys 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 @@ -37,7 +37,7 @@ export default class KeyAddCmd extends Command { 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. - + To generate a new SSH key pair, a nice guide can be found in GitHub's docs: https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent Skip the step about adding the key to a GitHub account, and instead add it to @@ -61,8 +61,6 @@ export default class KeyAddCmd extends Command { }), }; - public static usage = 'key add [path]'; - public static flags = { help: cf.help, }; diff --git a/src/commands/key/index.ts b/src/commands/key/index.ts index 895e7451..fa343133 100644 --- a/src/commands/key/index.ts +++ b/src/commands/key/index.ts @@ -38,8 +38,6 @@ export default class KeyCmd extends Command { }), }; - public static usage = 'key '; - public static flags = { help: cf.help, }; diff --git a/src/commands/key/rm.ts b/src/commands/key/rm.ts index 5e0ad100..aecad823 100644 --- a/src/commands/key/rm.ts +++ b/src/commands/key/rm.ts @@ -40,8 +40,6 @@ export default class KeyRmCmd extends Command { }), }; - public static usage = 'key rm '; - public static flags = { yes: cf.yes, help: cf.help, diff --git a/src/commands/keys/index.ts b/src/commands/keys/index.ts index ca81f366..af77abfb 100644 --- a/src/commands/keys/index.ts +++ b/src/commands/keys/index.ts @@ -27,8 +27,6 @@ export default class KeysCmd extends Command { `; public static examples = ['$ balena keys']; - public static usage = 'keys'; - public static flags = { help: cf.help, }; diff --git a/src/commands/leave/index.ts b/src/commands/leave/index.ts index 2365d007..a94d9a77 100644 --- a/src/commands/leave/index.ts +++ b/src/commands/leave/index.ts @@ -50,8 +50,6 @@ export default class LeaveCmd extends Command { }), }; - public static usage = 'leave [deviceIpOrHostname]'; - public static flags = { help: cf.help, }; diff --git a/src/commands/local/configure.ts b/src/commands/local/configure.ts index 53aa170d..0aace8f2 100644 --- a/src/commands/local/configure.ts +++ b/src/commands/local/configure.ts @@ -40,8 +40,6 @@ export default class LocalConfigureCmd extends Command { }), }; - public static usage = 'local configure '; - public static flags = { help: cf.help, }; diff --git a/src/commands/local/flash.ts b/src/commands/local/flash.ts index e2301718..1e6b137d 100644 --- a/src/commands/local/flash.ts +++ b/src/commands/local/flash.ts @@ -46,8 +46,6 @@ export default class LocalFlashCmd extends Command { }), }; - public static usage = 'local flash '; - public static flags = { drive: cf.drive, yes: cf.yes, diff --git a/src/commands/login/index.ts b/src/commands/login/index.ts index 70d6c1c6..653836c5 100644 --- a/src/commands/login/index.ts +++ b/src/commands/login/index.ts @@ -63,8 +63,6 @@ export default class LoginCmd extends Command { }), }; - public static usage = 'login'; - public static flags = { web: Flags.boolean({ default: false, diff --git a/src/commands/logout/index.ts b/src/commands/logout/index.ts index 5ea45963..ff14cb9c 100644 --- a/src/commands/logout/index.ts +++ b/src/commands/logout/index.ts @@ -26,8 +26,6 @@ export default class LogoutCmd extends Command { `; public static examples = ['$ balena logout']; - public static usage = 'logout'; - public async run() { await this.parse(LogoutCmd); await getBalenaSdk().auth.logout(); diff --git a/src/commands/logs/index.ts b/src/commands/logs/index.ts index 1ca17e72..7a6f9056 100644 --- a/src/commands/logs/index.ts +++ b/src/commands/logs/index.ts @@ -61,8 +61,6 @@ export default class LogsCmd extends Command { }), }; - public static usage = 'logs '; - public static flags = { 'max-retry': Flags.integer({ description: stripIndent` diff --git a/src/commands/notes/index.ts b/src/commands/notes/index.ts index fb3e38fc..6cf6de27 100644 --- a/src/commands/notes/index.ts +++ b/src/commands/notes/index.ts @@ -42,8 +42,6 @@ export default class NoteCmd extends Command { }), }; - public static usage = 'note <|note>'; - public static flags = { device: { exclusive: ['dev'], ...cf.device }, dev: Flags.string({ diff --git a/src/commands/orgs/index.ts b/src/commands/orgs/index.ts index f50604f8..62ec99cf 100644 --- a/src/commands/orgs/index.ts +++ b/src/commands/orgs/index.ts @@ -27,8 +27,6 @@ export default class OrgsCmd extends Command { `; public static examples = ['$ balena orgs']; - public static usage = 'orgs'; - public static flags = { help: cf.help, }; diff --git a/src/commands/os/build-config.ts b/src/commands/os/build-config.ts index 0b6d954a..0e88a58d 100644 --- a/src/commands/os/build-config.ts +++ b/src/commands/os/build-config.ts @@ -46,8 +46,6 @@ export default class OsBuildConfigCmd extends Command { }), }; - public static usage = 'os build-config '; - public static flags = { advanced: Flags.boolean({ description: 'show advanced configuration options', diff --git a/src/commands/os/configure.ts b/src/commands/os/configure.ts index d25f8ce2..1fd978cb 100644 --- a/src/commands/os/configure.ts +++ b/src/commands/os/configure.ts @@ -92,8 +92,6 @@ export default class OsConfigureCmd extends Command { }), }; - public static usage = 'os configure '; - public static flags = { advanced: Flags.boolean({ char: 'v', diff --git a/src/commands/os/download.ts b/src/commands/os/download.ts index c05eaaf7..9c902cca 100644 --- a/src/commands/os/download.ts +++ b/src/commands/os/download.ts @@ -62,8 +62,6 @@ export default class OsDownloadCmd extends Command { }), }; - public static usage = 'os download '; - public static flags = { output: Flags.string({ description: 'output path', diff --git a/src/commands/os/initialize.ts b/src/commands/os/initialize.ts index 322c1ab8..8e815e59 100644 --- a/src/commands/os/initialize.ts +++ b/src/commands/os/initialize.ts @@ -48,8 +48,6 @@ export default class OsInitializeCmd extends Command { }), }; - public static usage = 'os initialize '; - public static flags = { type: cf.deviceType, drive: cf.drive, diff --git a/src/commands/os/versions.ts b/src/commands/os/versions.ts index 9ba22a6b..7b813b78 100644 --- a/src/commands/os/versions.ts +++ b/src/commands/os/versions.ts @@ -40,8 +40,6 @@ export default class OsVersionsCmd extends Command { }), }; - public static usage = 'os versions '; - public static flags = { help: cf.help, esr: Flags.boolean({ diff --git a/src/commands/preload/index.ts b/src/commands/preload/index.ts index 7df4fc46..74d27ac8 100644 --- a/src/commands/preload/index.ts +++ b/src/commands/preload/index.ts @@ -80,8 +80,6 @@ export default class PreloadCmd extends Command { }), }; - public static usage = 'preload '; - public static flags = { fleet: cf.fleet, commit: Flags.string({ diff --git a/src/commands/push/index.ts b/src/commands/push/index.ts index 7693f7c4..a1a10521 100644 --- a/src/commands/push/index.ts +++ b/src/commands/push/index.ts @@ -99,8 +99,6 @@ export default class PushCmd extends Command { }), }; - public static usage = 'push '; - public static flags = { source: Flags.string({ description: stripIndent` diff --git a/src/commands/release/finalize.ts b/src/commands/release/finalize.ts index 2ddb422e..bcae1b6b 100644 --- a/src/commands/release/finalize.ts +++ b/src/commands/release/finalize.ts @@ -40,8 +40,6 @@ export default class ReleaseFinalizeCmd extends Command { '$ balena release finalize 1234567', ]; - public static usage = 'release finalize '; - public static flags = { help: cf.help, }; diff --git a/src/commands/release/index.ts b/src/commands/release/index.ts index a05d02a6..9f0a6960 100644 --- a/src/commands/release/index.ts +++ b/src/commands/release/index.ts @@ -42,8 +42,6 @@ export default class ReleaseCmd extends Command { '$ balena release d3f3151f5ad25ca6b070aa4d08296aca --json', ]; - public static usage = 'release '; - public static flags = { json: cf.json, help: cf.help, diff --git a/src/commands/release/invalidate.ts b/src/commands/release/invalidate.ts index f9f3f9b2..b4c68070 100644 --- a/src/commands/release/invalidate.ts +++ b/src/commands/release/invalidate.ts @@ -35,8 +35,6 @@ export default class ReleaseInvalidateCmd extends Command { '$ balena release invalidate 1234567', ]; - public static usage = 'release invalidate '; - public static flags = { help: cf.help, }; diff --git a/src/commands/release/validate.ts b/src/commands/release/validate.ts index 85ce4b45..eca3ce68 100644 --- a/src/commands/release/validate.ts +++ b/src/commands/release/validate.ts @@ -34,8 +34,6 @@ export default class ReleaseValidateCmd extends Command { '$ balena release validate 1234567', ]; - public static usage = 'release validate '; - public static flags = { help: cf.help, }; diff --git a/src/commands/releases/index.ts b/src/commands/releases/index.ts index 49bf3897..c5510113 100644 --- a/src/commands/releases/index.ts +++ b/src/commands/releases/index.ts @@ -38,8 +38,6 @@ export default class ReleasesCmd extends Command { '$ balena releases myorg/myfleet --json', ]; - public static usage = 'releases '; - public static flags = { json: cf.json, help: cf.help, diff --git a/src/commands/scan/index.ts b/src/commands/scan/index.ts index fd6fdcc2..dbe68a14 100644 --- a/src/commands/scan/index.ts +++ b/src/commands/scan/index.ts @@ -38,8 +38,6 @@ export default class ScanCmd extends Command { '$ balena scan --verbose', ]; - public static usage = 'scan'; - public static flags = { verbose: Flags.boolean({ default: false, diff --git a/src/commands/settings/index.ts b/src/commands/settings/index.ts index f54c4db0..71d3d116 100644 --- a/src/commands/settings/index.ts +++ b/src/commands/settings/index.ts @@ -27,8 +27,6 @@ export default class SettingsCmd extends Command { `; public static examples = ['$ balena settings']; - public static usage = 'settings'; - public static flags = { help: cf.help, }; diff --git a/src/commands/ssh/index.ts b/src/commands/ssh/index.ts index 477736ff..f44e2ee6 100644 --- a/src/commands/ssh/index.ts +++ b/src/commands/ssh/index.ts @@ -75,8 +75,6 @@ export default class SshCmd extends Command { }), }; - public static usage = 'ssh [service]'; - public static flags = { port: Flags.integer({ description: stripIndent` diff --git a/src/commands/support/index.ts b/src/commands/support/index.ts index 84af6f4c..58550cb2 100644 --- a/src/commands/support/index.ts +++ b/src/commands/support/index.ts @@ -52,8 +52,6 @@ export default class SupportCmd extends Command { }), }; - public static usage = 'support '; - public static flags = { device: Flags.string({ description: 'comma-separated list (no spaces) of device UUIDs', diff --git a/src/commands/tag/rm.ts b/src/commands/tag/rm.ts index 057418f4..b3cf0aa7 100644 --- a/src/commands/tag/rm.ts +++ b/src/commands/tag/rm.ts @@ -45,8 +45,6 @@ export default class TagRmCmd extends Command { }), }; - public static usage = 'tag rm '; - public static flags = { fleet: { ...cf.fleet, diff --git a/src/commands/tag/set.ts b/src/commands/tag/set.ts index d77e4190..306e90de 100644 --- a/src/commands/tag/set.ts +++ b/src/commands/tag/set.ts @@ -58,7 +58,6 @@ export default class TagSetCmd extends Command { // Required for supporting empty string ('') `value` args. public static strict = false; - public static usage = 'tag set [value]'; public static flags = { fleet: { diff --git a/src/commands/tags/index.ts b/src/commands/tags/index.ts index 9653c396..cb13e7cc 100644 --- a/src/commands/tags/index.ts +++ b/src/commands/tags/index.ts @@ -38,8 +38,6 @@ export default class TagsCmd extends Command { '$ balena tags --release b376b0e544e9429483b656490e5b9443b4349bd6', ]; - public static usage = 'tags'; - public static flags = { fleet: { ...cf.fleet, diff --git a/src/commands/tunnel/index.ts b/src/commands/tunnel/index.ts index 91be2fe6..299943a7 100644 --- a/src/commands/tunnel/index.ts +++ b/src/commands/tunnel/index.ts @@ -78,8 +78,6 @@ export default class TunnelCmd extends Command { }), }; - public static usage = 'tunnel '; - public static flags = { port: Flags.string({ description: diff --git a/src/commands/util/available-drives.ts b/src/commands/util/available-drives.ts index ac71d201..705e157e 100644 --- a/src/commands/util/available-drives.ts +++ b/src/commands/util/available-drives.ts @@ -27,8 +27,6 @@ export default class UtilAvailableDrivesCmd extends Command { Does not list system drives. `; - public static usage = 'util available-drives'; - public static flags = { help: cf.help, }; diff --git a/src/commands/version/index.ts b/src/commands/version/index.ts index 9c59a8cc..9e1c3c86 100644 --- a/src/commands/version/index.ts +++ b/src/commands/version/index.ts @@ -49,8 +49,6 @@ export default class VersionCmd extends Command { `$ balena -v`, ]; - public static usage = 'version'; - public static offlineCompatible = true; public static flags = { diff --git a/src/commands/whoami/index.ts b/src/commands/whoami/index.ts index adc81acd..7c01b0f2 100644 --- a/src/commands/whoami/index.ts +++ b/src/commands/whoami/index.ts @@ -27,8 +27,6 @@ export default class WhoamiCmd extends Command { public static examples = ['$ balena whoami']; - public static usage = 'whoami'; - public static authenticated = true; public async run() { diff --git a/src/help.ts b/src/help.ts index e9644fee..5c78b2d7 100644 --- a/src/help.ts +++ b/src/help.ts @@ -14,9 +14,11 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import type { Command } from '@oclif/core'; import { Help } from '@oclif/core'; import * as indent from 'indent-string'; import { getChalk } from './utils/lazy'; +import type { ResolvableReturnType } from 'balena-sdk/typings/utils'; // Partially overrides standard implementation of help plugin // https://github.com/oclif/plugin-help/blob/master/src/index.ts @@ -37,8 +39,6 @@ function getHelpSubject(args: string[]): string | undefined { } export default class BalenaHelp extends Help { - public static usage: 'help [command]'; - public async showHelp(argv: string[]) { const chalk = getChalk(); const subject = getHelpSubject(argv); @@ -96,9 +96,9 @@ export default class BalenaHelp extends Help { }) .filter((c): c is (typeof commands)[0] => !!c); - let usageLength = 0; + let cmdLength = 0; for (const cmd of primaryCommands) { - usageLength = Math.max(usageLength, cmd.usage?.length || 0); + cmdLength = Math.max(cmdLength, cmd.id.length); } let additionalCmdSection: string[]; @@ -112,16 +112,15 @@ export default class BalenaHelp extends Help { // Find longest usage, and pad usage of first command in each category // This is to ensure that both categories align visually for (const cmd of additionalCommands) { - usageLength = Math.max(usageLength, cmd.usage?.length || 0); + cmdLength = Math.max(cmdLength, cmd.id.length); } if ( - typeof primaryCommands[0].usage === 'string' && - typeof additionalCommands[0].usage === 'string' + typeof primaryCommands[0].id === 'string' && + typeof additionalCommands[0].id === 'string' ) { - primaryCommands[0].usage = primaryCommands[0].usage.padEnd(usageLength); - additionalCommands[0].usage = - additionalCommands[0].usage.padEnd(usageLength); + primaryCommands[0].id = primaryCommands[0].id.padEnd(cmdLength); + additionalCommands[0].id = additionalCommands[0].id.padEnd(cmdLength); } additionalCmdSection = [ @@ -145,7 +144,7 @@ prevent exit with an error as per Deprecation Policy See: https://git.io/JRHUW#deprecation-policy`, ], ]; - globalOps[0][0] = globalOps[0][0].padEnd(usageLength); + globalOps[0][0] = globalOps[0][0].padEnd(cmdLength); const { deprecationPolicyNote, reachingOut } = require('./utils/messages') as typeof import('./utils/messages'); @@ -185,15 +184,20 @@ See: https://git.io/JRHUW#deprecation-policy`, return outLines.join('\n'); } - protected formatCommands(commands: any[]): string { + protected formatCommands( + commands: Array< + Command.Loadable | ResolvableReturnType + >, + ): string { if (commands.length === 0) { return ''; } const body = this.renderList( - commands - .filter((c) => c.usage != null && c.usage !== '') - .map((c) => [c.usage, this.formatDescription(c.description)]), + commands.map((c) => [ + c.id.replaceAll(':', ' '), + this.formatDescription(c.description), + ]), { spacer: '\n', stripAnsi: this.opts.stripAnsi, diff --git a/src/hooks/prerun/track.ts b/src/hooks/prerun/track.ts index c57061aa..24152a1b 100644 --- a/src/hooks/prerun/track.ts +++ b/src/hooks/prerun/track.ts @@ -34,13 +34,11 @@ export const trackPromise = new Promise((resolve) => { */ const hook: Hook<'prerun'> = async function (options) { const events = await import('../../events'); - const usage: string | string[] | undefined = options.Command.usage; - const cmdSignature = - usage == null ? '*' : typeof usage === 'string' ? usage : usage.join(' '); + const cmd = options.Command.id; // Intentionally do not await for the track promise here, in order to // run the command tracking and the command itself in parallel. - trackResolve(events.trackCommand(cmdSignature)); + trackResolve(events.trackCommand(cmd)); }; export default hook; diff --git a/src/utils/oclif-utils.ts b/src/utils/oclif-utils.ts index ceac7501..5dc374ee 100644 --- a/src/utils/oclif-utils.ts +++ b/src/utils/oclif-utils.ts @@ -15,33 +15,7 @@ * limitations under the License. */ -/** - * This class is a partial copy-and-paste of - * @oclif/plugin-help/command/CommandHelp, which is used to generate oclif's - * command help output. - */ -export class CommandHelp { - constructor(public command: { args?: { [name: string]: any } }) {} - - protected arg(name: string, required: boolean): string { - name = name.toUpperCase(); - if (required) { - return `${name}`; - } - return `[${name}]`; - } - - public defaultUsage(): string { - const argsObject = this.command.args ?? {}; - - return Object.entries(argsObject) - .filter(([_name, { hidden }]) => !hidden) - .map(([name, { required }]) => this.arg(name, required)) - .join(' '); - } -} - -/** Convert e.g. 'env add NAME [VALUE]' to 'env add [value]' */ +/** Convert e.g. 'env set NAME [VALUE]' to 'env set [value]' */ export function capitanoizeOclifUsage( oclifUsage: string | string[] | undefined, ): string {