Skip to content

optional-capabilities.md

Latest commit

 

History

History
191 lines (146 loc) · 8.25 KB

optional-capabilities.md

File metadata and controls

191 lines (146 loc) · 8.25 KB
Raw

Optional capabilities

This guide covers choices for the required Node.js setup, plus optional tools and settings that extend Ballin. The defaults keep updates predictable while letting you opt in to broader automation.

Working with settings

Use ballin config to read and update local settings. Settings use dot paths, such as update.cleanup or analytics.enabled.

ballin config
ballin config get update.cleanup
ballin config set update.cleanup false
ballin config reset
ballin config --help

ballin config prints the full config, get prints one value, and set updates an existing setting. Use ballin config --help for usage, even if the config file is missing or unreadable.

Use ballin config reset to recover a missing or malformed config file. This restores defaults and replaces saved settings. For read or save errors, check the config file's permissions and its parent directory before retrying.

Node.js

Node.js is required by Ballin; install it using whichever method fits your environment. For development, we recommend nvm with the latest Node.js long-term support (LTS) release. It supports switching versions, project-specific .nvmrc files, and a user-local installation.

Follow nvm's official installation and shell setup instructions, then install Node.js LTS:

nvm install --lts

Installed commands use the node found on your shell PATH, so make sure new terminal sessions use a supported Node.js version too.

After installing Ballin, optionally let ballin update install newer LTS releases:

ballin config set update.nvm true

update.nvm runs nvm install --lts; it does not update nvm itself. It defaults to false because enabling it opts into newer LTS releases, and installing a new Node.js version does not migrate your globally installed npm packages automatically. If nvm cannot be loaded, ballin update reports the failure and continues with its remaining updates. A failure to capture nvm's updated environment is handled the same way; later stages use the previous environment.

For a simpler setup, install Homebrew's current Node.js release instead:

brew install node

With this option, Homebrew manages Node.js updates along with your other formulae. The update.nvm setting does not apply.

Mac App Store apps

Install mas with Homebrew to add Mac App Store support:

brew install mas

When mas is available, ballin update updates installed App Store apps and ballin backup includes the installed-app list in your backup. No configuration setting is required.

Private repository backups

Newly configured backups use private GitHub.com repositories owned by a personal account, accessed through GitHub CLI. Backup is optional; declining it leaves a healthy maintenance-only installation and makes no gh calls.

ballin backup setup [repository-name]

Fresh setup offers create or reconnect, reviews one local sensitive-source choice, and confirms before remote or linkage changes. The effective gh credential can come from an environment token; Ballin shows the selected account and never logs in, switches accounts, or expands scopes automatically. Read-only access supports reconnect and recovery without granting write permission. See setup and recovery.

backup.repository identifies the selected destination. The fixed inventory and filtered-preference baseline is always selected; backup.includeSensitive defaults to "false"; enabling it adds raw configuration and pipx metadata. The setting accepts native booleans or exact "true"/"false" strings. Destination and consent stay local. Changing sensitive consent later changes future capture selection, not saved files or history; review source sensitivity first.

After new linkage, setup asks whether updates should run backups automatically, with yes as the default. Change that independent choice later with:

ballin config set update.backup true
ballin config set update.backup false

The repository URL alone does not grant access, but GitHub and authorized accounts or tokens can read private backups. Even baseline inventories can expose identities, private URLs, and paths; Ballin does not scan or redact credentials. GitHub controls account-based commit author/committer attribution; Ballin changes no global Git identity configuration. GitHub retains history, but Ballin provides no history navigation, rollback, or revision picker.

Use ballin backup open or ballin backup read <file> for read-only recovery, and ballin backup disconnect to clear local linkage and disable automatic backups. Use only one Mac to back up to a destination. Stop using the previous Mac for backups before publishing from a replacement Mac. See conflicts.

Existing configured Gists retain their current capture/read/open behavior and host repair, including Enterprise hosts. Secret Gists remain readable by anyone with their URL or ID. No new Gist setup is available. Migration and Gist retirement remain in #334.

Readiness checks

Use ballin doctor to check the managed environment. Maintenance-only Ballin is healthy and does not invoke gh; configured backup failures affect overall health. See Supported capabilities for the checks and their limitations.

ballin doctor

Recovering Ballin preferences

Reconnecting to a backup can recover supported Ballin preferences for cleanup, self-updates, macOS updates, and Node/npm updates, plus an analytics opt-out. Existing local choices take precedence. Recovery affects later maintenance; it does not run updates, apply dotfiles, or install packages.

The ballin_config snapshot saves only those supported preferences. Destination identity, custom settings, analytics identity, automatic-backup choices, and sensitive-source approval stay local. A newly configured backup gets its own automatic-backup and sensitive-source choices during setup. See Backup design for the exact allowlists and restoration rules.

Analytics

Ballin can send minimal anonymous usage analytics after a first-run notice. See Analytics for what is sent, what is never sent, and how long it is kept.

Disable persistently:

ballin config set analytics.enabled false

ballin update settings

Change a setting with ballin config set update.<name> true or ballin config set update.<name> false.

ballin update validates these settings before running any integration. Missing known settings use bundled defaults in memory for the current run and appear in one warning. The config file remains unchanged, and this behavior does not depend on self-update. Malformed JSON, invalid config structure, or known values other than booleans and canonical "true" or "false" strings fail before any integration runs. Later stages continue after failures; if several fail, the command returns the last nonzero stage status.

Setting Default Behavior
update.cleanup true Runs brew cleanup after upgrading Homebrew packages.
update.selfUpdate true Updates ballin-scripts when ballin update runs, then checks Ballin readiness if the update succeeds.
update.backup false Runs ballin backup to back up your development environment. Configure a destination with ballin backup setup before enabling it; an explicitly requested unconfigured backup stage fails with setup guidance.
update.softwareupdate true Installs available macOS updates with softwareupdate.
update.nvm false Installs the latest Node.js LTS release through a configured nvm installation. See Node.js for the setup and tradeoffs.
update.npm false Runs npm update -g across globally installed packages. This is a separate update step from the npm version supplied with Node.js. It defaults to false because it can change all global tools at once, while many tools can instead stay project-local or run through npx.