devops¶

DevOps operations, package management, and system administration.

Usage¶

devops [OPTIONS] COMMAND [ARGS]...

Commands Overview¶

Command	Shortcut	Description
`install`	`i`	Install packages and package groups
`repos`	`r`	Manage development repositories
`config`	`c`	Configuration management
`data`	`d`	Data management
`self`	`s`	Self management
`network`	`n`	Network management
`execute`	`e`	Execute scripts

install¶

The primary package installation command. Supports single packages, multiple packages, package groups, and interactive selection.

devops install [OPTIONS] [WHICH]

Arguments¶

Argument	Description
`WHICH`	Comma-separated list of package names, group name, or GitHub/binary URL

Options¶

Option	Short	Description
`--group`	`-g`	Treat `WHICH` as a package group name
`--interactive`	`-i`	Interactive selection with TV/fzf interface

Installation Modes¶

Single Package¶

# Install a single package by name
devops install btop
devops install fd
devops install yazi

Multiple Packages¶

# Install multiple packages (comma-separated, no spaces)
devops install btop,fd,bat,rg,fzf

# With spaces (use quotes)
devops install "btop, fd, bat, rg"

Package Groups¶

Install predefined bundles of related packages:

# Install terminal essentials (40+ tools)
devops install termabc --group
devops install termabc -g

# Install AI coding assistants
devops install agents -g

# Install full development environment
devops install dev -g

# Install system monitors
devops install sys-monitor -g

Interactive Mode¶

Launch an interactive selector with all available packages:

devops install --interactive
devops install -i

Features: - Shows installation status (✅ installed, ❌ not installed) - Package descriptions displayed - Multi-select supported - Package groups prefixed with 📦

From GitHub URL¶

Install directly from a GitHub repository:

# The installer will show available release assets for selection
devops install https://github.com/sharkdp/fd
devops install https://github.com/BurntSushi/ripgrep

From Binary URL¶

Install from a direct download URL:

devops install https://example.com/tool-v1.0-linux-amd64.tar.gz

Available Package Groups¶

Group	Description	Contents
`sysabc`	System essentials	Package managers, build tools, bun
`termabc`	Terminal power tools	60+ CLI tools (search, monitors, shell)
`gui`	GUI applications	brave, code, git
`dev`	Full dev environment	80+ tools across all categories
`dev-utils`	Development utilities	devcontainer, rust-analyzer, evcxr, geckodriver
`term-eye-candy`	Terminal visuals	lolcatjs, figlet-cli, boxes, cowsay
`agents`	AI assistants	aider, aichat, copilot, gemini, opencode-ai, mods, q, ...
`terminal-emulator`	Terminal emulators	Alacritty, Wezterm, warp, vtm, nushell
`shell`	Shell enhancements	zellij, mprocs, mcfly, atuin, starship
`browsers`	Web browsers	Brave, browsh, carbonyl
`code-editors`	Code editors	code, Cursor, lvim
`code-analysis`	Code & Git tools	lazygit, gitui, delta, gh, tokei, hyperfine
`db`	Database tools	SqliteBrowser, duckdb, DBeaver, rainfrog
`media`	Media players	ytui-music, termusic
`file-sharing`	File sharing	ngrok, cloudflared, ffsend, syncthing, rclone
`productivity`	Productivity	espanso, bitwarden, glow, gum, pandoc
`sys-monitor`	System monitors	btop, btm, procs, bandwhich, fastfetch
`search`	Search & file tools	fd, fzf, rg, bat, yazi, zoxide, dust

Listing Available Groups¶

# Show all available groups with their packages
devops install -g

# Output shows:
# 📦 sysabc              --   sysabc
# 📦 termabc             --   nano|lazygit|onefetch|...
# 📦 agents              --   aider|aichat|copilot|...

Examples¶

# Essential terminal setup (recommended first install)
devops install sysabc -g && devops install termabc -g

# Install all AI coding assistants
devops install agents -g

# Selective installation
devops install btop,fd,rg,fzf,bat,zoxide,yazi

# Interactive browse and install
devops install -i

# Install from specific GitHub repo
devops install https://github.com/jesseduffield/lazygit

repos¶

Manage development repositories.

devops repos [SUBCOMMAND] [ARGS]...

Handles cloning, updating, analyzing, and maintaining development repositories.

Current devops repos --help exposes:

Command	Description
`sync`	Clone repositories described by a `repos.json` specification
`register`	Record repositories into a `repos.json` specification
`action`	Run pull/commit/push actions across repositories
`analyze`	Analyze repository development over time
`guard`	Securely sync a git repository to and from cloud storage with encryption
`viz`	Visualize repository activity using Gource
`count-lines`	Count current Python lines and historical edits
`config-linters`	Add linter config files to a git repository
`cleanup`	Clean repository directories from cache files

Hidden compatibility aliases still exist for older checkout flows, but the current path is sync --checkout-to-commit or sync --checkout-to-branch.

sync¶

Clone or check out repositories described by a repos.json specification.

devops repos sync [DIRECTORY] [OPTIONS]

Key options from current help:

Option	Description
`--specs-path`, `-s`	Explicit path to the `repos.json` specification
`--interactive`, `-i`	Choose a backed-up `repos.json` interactively
`--checkout-to-commit`, `-ctc`	Check out commits pinned in the specification
`--checkout-to-branch`, `-ctb`	Check out the main branch from the specification

Important behavior from the implementation:

--checkout-to-commit and --checkout-to-branch are mutually exclusive
Without --specs-path, machineconfig derives the expected repos.json from the target directory
With --interactive, machineconfig searches backed-up repos.json files and lets you choose which one to apply

Examples:

# Clone from the default repos.json associated with a directory
devops repos sync ~/code

# Use an explicit spec file
devops repos sync ~/code --specs-path ~/backups/work/repos.json

# Check out the branches declared in the spec
devops repos sync ~/code --checkout-to-branch

# Interactively choose from backed-up specs
devops repos sync --interactive

register¶

Scan a directory of repositories and write a repos.json specification for it.

devops repos register [DIRECTORY]

register currently takes only the optional repository root argument. The generated spec is intended to become the source for future repos sync runs.

Example:

devops repos register ~/code

action¶

Run pull, commit, and push actions across one repository or a whole tree of repositories.

devops repos action [DIRECTORY] [OPTIONS]

Key options from current help:

Option	Description
`--recursive`, `-r`	Recurse into nested repositories
`--uv-sync`, `-u`	Run `uv sync` automatically after pulls
`--pull`, `-P`	Pull changes
`--commit`, `-c`	Commit changes
`--push`, `-p`	Push changes

At least one of --pull, --commit, or --push is required.

Examples:

# Pull every repo below a root directory
devops repos action ~/code --recursive --pull

# Pull and run uv sync where relevant
devops repos action ~/code --recursive --pull --uv-sync

# Commit and push one repo
devops repos action ~/code/machineconfig --commit --push

analyze¶

Analyze repository development over time.

devops repos analyze REPO_PATH

This delegates to the plotting-oriented repository analyzer.

Example:

devops repos analyze ~/code/machineconfig

guard¶

Securely sync a git repository to or from cloud storage with encryption.

devops repos guard REPO [OPTIONS]

Key options from current help:

Option	Description
`--cloud`, `-c`	Cloud storage profile name
`--message`, `-m`	Commit message for local changes
`--on-conflict`, `-o`	Conflict strategy such as `ask`, `push-local-merge`, `overwrite-local`, `stop-on-conflict`, or `remove-rclone-conflict`
`--password`	Password for encryption and decryption

Example:

devops repos guard ~/code/private-repo --cloud myremote --message "sync before travel"

viz¶

Visualize repository history with Gource, either live or rendered to video.

devops repos viz [OPTIONS]

Commonly used options from current help:

Option	Description
`--repo`, `-r`	Repository to visualize
`--output`, `-o`	Render to a video file instead of interactive mode
`--resolution`, `-res`	Output resolution
`--seconds-per-day`, `-spd`	Playback speed
`--start-date`	Lower date bound
`--stop-date`	Upper date bound
`--title`, `-t`	Visualization title
`--self`	Clone and visualize the machineconfig repository

The current help also exposes additional rendering controls for hidden layers, viewport, avatars, file limits, framerate, background color, and camera mode.

Examples:

# Interactive visualization
devops repos viz --repo ~/code/machineconfig

# Render to video
devops repos viz --repo ~/code/machineconfig --output machineconfig.mp4 --resolution 1280x720

count-lines¶

Count Python lines of code in the current state and through repository history.

devops repos count-lines REPO_PATH

Example:

devops repos count-lines ~/code/machineconfig

config-linters¶

Copy standard linter config files into a git repository.

devops repos config-linters [DIRECTORY] [OPTIONS]

Key options from current help:

Option	Description
`--linter`, `-t`	Restrict the copy to `ruff`, `mypy`, `pylint`, `flake8`, or `ty`

Without --linter, machineconfig copies the full supported set of linter config files.

Examples:

devops repos config-linters ~/code/myrepo
devops repos config-linters ~/code/myrepo --linter ruff

cleanup¶

Clean repository directories from cache files.

devops repos cleanup [REPO] [OPTIONS]

Key options from current help:

Option	Description
`--recursive`, `-r`	Recurse into nested repositories under the given directory

Without --recursive, the target must already be a git repository. With --recursive, machineconfig searches for nested .git directories and cleans each repository it finds.

Examples:

# Clean one repo
devops repos cleanup ~/code/machineconfig

# Clean every repo below a root directory
devops repos cleanup ~/code --recursive

The nested help screens render shortened usage such as devops sync ..., devops action ..., or devops viz ..., but the full entrypoints remain devops repos sync ..., devops repos action ..., and devops repos viz ....

config¶

Configuration management.

devops config [SUBCOMMAND] [ARGS]...

Manage dotfiles, packaged assets, example config generation, and terminal profile/theme setup.

Current devops config --help exposes:

Command	Description
`sync`	Apply dotfile mappings with `symlink` or `copy`
`register`	Register a file or directory into the user mapper
`edit`	Open the library or user `mapper.toml`
`export-dotfiles`	Export `~/dotfiles` for machine migration
`import-dotfiles`	Import an exported dotfiles archive
`copy-assets`	Copy packaged scripts and settings onto the machine
`dump`	Write example configuration files such as `.ve.example.yaml`
`terminal`	Shell profile and terminal theme commands

sync¶

Apply the current dotfile mapping set.

devops config sync <up|down> --sensitivity <public|private|all> --method <symlink|copy> [OPTIONS]

Key arguments and options from current help:

Item	Description
`direction`	Required. Use `up` to push default paths into the managed location, or `down` to apply managed files back to default paths
`--sensitivity`, `-s`	Required. Choose `private`, `public`, or `all`
`--method`, `-m`	Required. Use `symlink` or `copy`
`--repo`, `-r`	Select mappings from `library`, `user`, or `all`
`--on-conflict`, `-o`	Conflict policy such as `throw-error`, `overwrite-self-managed`, or `overwrite-default-path`
`--which`, `-w`	Limit the run to specific mapping names, or use `all`

If --which is omitted, the command falls back to interactive selection.

For library-backed public configs, copy packaged settings first when needed:

devops config copy-assets settings

Examples:

# Apply all public mappings with symlinks
devops config sync down --sensitivity public --method symlink --which all

# Push local private config changes back into the managed backup area
devops config sync up --sensitivity private --method copy --repo user

register¶

Register a new config file or directory into the self-managed dotfiles area and, by default, record that mapping in the user mapper.

devops config register [OPTIONS] FILE

Key options from current help:

Option	Description
`--method`, `-m`	Store it with `copy` or `symlink` semantics
`--on-conflict`, `-o`	Conflict strategy during the initial transfer
`--sensitivity`, `-s`	Mark the mapping as `private` or `public`
`--destination`, `-d`	Override the default self-managed destination
`--section`, `-se`	Section name to write inside the user mapper
`--os`	Restrict the mapping to one OS or a comma-separated list
`--shared`, `-sh`	Place the managed file under a shared destination layout
`--record`, `-r`	Record the mapping in the user mapper file

Examples:

# Register a private file and record it in the default mapper section
devops config register ~/.config/htop/htoprc --sensitivity private

# Register a public directory with symlink semantics
devops config register ~/.config/nvim --method symlink --sensitivity public --section editors

edit¶

Open the dotfile mapper in nano, hx, or code.

devops config edit --editor hx --repo user

The user mapper is created automatically if it does not exist yet.

export-dotfiles¶

Package and encrypt ~/dotfiles for transfer to another machine.

devops config export-dotfiles <password>

Optional transfer flags:

Option	Description
`--over-internet`, `-i`	Internet-transfer flag present in the CLI, but the current implementation is not finished
`--over-ssh`, `-s`	Use SSH/SCP-style transfer

import-dotfiles¶

Import an encrypted dotfiles archive from a local path or URL.

devops config import-dotfiles --url /path/to/dotfiles.zip.enc --pwd <password>

copy-assets¶

Copy packaged helper assets from the library onto the current machine.

devops config copy-assets <scripts|settings|all>

Examples:

devops config copy-assets scripts
devops config copy-assets all

dump¶

Write example configuration files into the current directory.

devops config dump --which ve

At the moment, ve writes .ve.example.yaml in the current working directory.

terminal¶

Terminal setup lives under a nested Typer app:

devops config terminal [SUBCOMMAND] [ARGS]...

devops config terminal --help currently exposes:

Command	Description
`config-shell`	Create or configure the default shell profile or Nushell profile
`starship-theme`	Interactive Starship prompt theme selection
`pwsh-theme`	Interactive PowerShell prompt theme selection
`wezterm-theme`	Interactive WezTerm theme selection
`ghostty-theme`	Interactive Ghostty theme selection
`windows-terminal-theme`	Interactive Windows Terminal color scheme selection

The nested help screens render Usage: devops terminal ..., but the full entrypoint remains devops config terminal ....

Examples:

devops config terminal config-shell --which default
devops config terminal config-shell --which nushell
devops config terminal wezterm-theme
devops config terminal ghostty-theme

data¶

Data backup and retrieval operations.

devops data [SUBCOMMAND] [ARGS]...

Back up configured files and directories to cloud storage, retrieve them back, and maintain the backup item registry.

Current devops data --help exposes:

Command	Description
`sync`	Generate backup or retrieve commands through `cloud copy`
`register`	Add or update a backup entry in the user data-mapping file
`edit`	Open the user or library backup configuration file

sync¶

Generate backup or restore commands for registered items.

devops data sync <up|down> [OPTIONS]

up means backup to the cloud. down means retrieve from the cloud.

Key options from current help:

Option	Description
`--cloud`, `-c`	Select the rclone config name to use
`--which`, `-w`	Choose specific items, a whole group, or `all`
`--repo`, `-r`	Load backup entries from `library`, `user`, or `all`

If --which is omitted, the command falls back to interactive selection. The selector accepts:

a group name such as dotfiles
a specific item such as dotfiles.bashrc
all for every applicable entry

Examples:

# Generate commands to back up every registered item
devops data sync up --which all

# Generate commands to restore one group from the user backup config
devops data sync down --repo user --which dotfiles

# Generate commands for selected entries with a specific cloud config
devops data sync up --cloud myremote --which dotfiles.bashrc,history.shell

devops data sync filters entries by the current OS and then prints the generated cloud copy script based on each item's os, zip, encrypt, and rel2home fields.

register¶

Add or update one entry inside the user backup configuration file at ~/dotfiles/machineconfig/mapper_data.toml.

devops data register [OPTIONS] PATH_LOCAL

Key options from current help:

Option	Description
`--group`, `-g`	Target group/table name inside the config file
`--name`, `-n`	Override the generated entry name
`--path-cloud`, `-C`	Override the remote path; omit it to let machineconfig deduce one
`--zip`, `-z`	Zip before upload
`--encrypt`, `-e`	Encrypt before upload
`--rel2home`, `-r`	Store the local path relative to your home directory
`--os`, `-o`	Restrict the entry to `linux`, `darwin`, `windows`, or a comma-separated list

Examples:

# Register a config directory for encrypted, zipped backup
devops data register ~/.config/wezterm --group dotfiles --zip --encrypt

# Register a directory with an explicit cloud path
devops data register ~/Documents/work --group documents --path-cloud backups/work --os linux,darwin

If --name is omitted, the command generates one from the local path and OS filter.

edit¶

Open the backup configuration file in nano, hx, or code.

devops data edit --editor hx --repo user

The user backup config is created automatically if it does not exist yet.

Backup File Layout¶

The user backup file uses grouped TOML tables. A representative entry looks like this:

[dotfiles]
wezterm = { path_local = "~/.config/wezterm", path_cloud = "^", encrypt = true, zip = true, rel2home = true, os = "linux,darwin" }

Selection behavior for devops data sync --which ...:

dotfiles selects the whole group
dotfiles.wezterm selects one item
all selects every applicable item

The nested help screens render Usage: devops sync ..., devops register ..., and devops edit ..., but the full entrypoints remain devops data sync ..., devops data register ..., and devops data edit ....

self¶

Self management commands.

devops self [SUBCOMMAND] [ARGS]...

Manage machineconfig itself: upgrades, bootstrap scripts, install flows, docs preview, CLI graph exploration, and repo-local developer utilities.

Current devops self --help exposes:

Command	Description	Availability
`update`	Upgrade machineconfig and optionally refresh copied assets or public config links	Always
`init`	Print or run packaged init/setup scripts	Always
`status`	Inspect shell profile, apps, symlinks, dotfiles, and related machine state	Always
`install`	Install machineconfig locally, export an offline image, or run the interactive setup flow	Always
`explore`	Inspect the CLI graph in terminal, DOT, Plotly, or TUI form	Always
`build-docker`	Build Docker images from the repo script	Only when `~/code/machineconfig` exists
`security`	Run security and installer-audit helpers	Only when `~/code/machineconfig` exists
`docs`	Serve the local docs preview, optionally after rebuilding	Only when `~/code/machineconfig` exists
`assets`	Regenerate the checked-in CLI graph snapshot and chart artifacts	Only when `~/code/machineconfig` exists
`readme`	Fetch and render the project README in the terminal	Always

The nested help screens render shortened usage such as Usage: devops update ..., but the full entrypoints remain devops self ... and devops self security ....

update¶

Upgrade the installed tool and optionally re-apply local assets or public configs.

devops self update [OPTIONS]

Key options from current help:

Option	Description
`--assets-copy`, `-a`	Copy packaged assets onto the current machine after the update
`--link-public-configs`, `-b`	Re-link public configs after the update

Current behavior:

If ~/code/machineconfig exists, the command runs uv self update, git pull, and reinstalls the repo checkout as an editable tool.
Otherwise it updates uv and upgrades the installed machineconfig tool package.
On non-Windows platforms, --assets-copy and --link-public-configs trigger follow-up local configuration work after the tool update.

Examples:

devops self update
devops self update --no-assets-copy
devops self update --link-public-configs

init¶

Print one of the packaged init/setup scripts, or execute it immediately with --run.

devops self init [OPTIONS] [WHICH]

Supported WHICH values from current help:

Value	Meaning
`init`	Print the shell init script for the current platform
`ia`	Print the interactive setup bootstrap script
`live`	Print the live-from-GitHub bootstrap script

Key option:

Option	Description
`--run`, `-r`	Run the selected script instead of printing it

Examples:

devops self init
devops self init ia
devops self init live --run

status¶

Run the self-audit report for the current machine.

devops self status

This command delegates to the status helper that inspects installed tools, shell profile state, symlinks, and managed config layout.

install¶

Install machineconfig, clone a local development checkout when requested, export an offline image, or hand off to the interactive setup flow.

devops self install [OPTIONS]

Key options from current help:

Option	Description
`--copy-assets`, `-a`	Copy packaged assets after installation
`--dev`, `-d`	Install from a local development checkout instead of PyPI
`--export`, `-e`	Export installation files for an offline image
`--interactive`, `-i`	Run the interactive configuration flow instead of a direct install

Current behavior:

--interactive switches into the guided setup flow immediately.
--export produces the offline-installation image and exits.
--dev clones ~/code/machineconfig first when that checkout does not already exist, then installs it editable.
Without a local checkout, the default path installs the published tool package.

Examples:

devops self install
devops self install --dev
devops self install --interactive
devops self install --export

explore¶

CLI graph inspection lives under a nested Typer app:

devops self explore [SUBCOMMAND] [ARGS]...

Current devops self explore --help exposes:

Command	Description
`search`	Search all `cli_graph.json` command entries
`tree`	Render a rich tree view in the terminal
`dot`	Export the graph as Graphviz DOT
`sunburst`	Render a Plotly sunburst view
`treemap`	Render a Plotly treemap view
`icicle`	Render a Plotly icicle view
`tui`	Open the full-screen Textual navigator

search¶

Interactive fuzzy-search over the generated CLI graph JSON. By default it runs --help for the selected command or group; use --show-json to print the raw graph entry.

devops self explore search [OPTIONS]

Key option:

Option	Description
`--graph-path`, `-g`	Override the path to `cli_graph.json`
`--show-json`	Print the selected `cli_graph.json` entry instead of running help

Representative JSON result excerpt:

{
  "kind": "command",
  "name": "tree",
  "help": "🌳 <t> Render a rich tree view in the terminal.",
  "source": {
    "file": "src/machineconfig/scripts/python/graph/visualize/cli_graph_app.py",
    "module": "machineconfig.scripts.python.graph.visualize.cli_graph_app",
    "callable": "tree"
  }
}

tree¶

Render the graph as a terminal tree.

devops self explore tree [OPTIONS]

Key options from current help:

Option	Description
`--show-help`	Include help text in each node label
`--show-aliases`	Include hidden aliases in labels
`--max-depth`, `-d`	Limit the rendered depth

Example:

devops self explore tree --max-depth 2

Representative output:

mcfg - MachineConfig CLI - Manage your machine configurations and workflows
├── devops - 🔧 DevOps operations
│   ├── install - 🔧 <i> Install essential packages
│   ├── repos - 📁 <r> Manage development repositories
│   ├── config - 🧰 <c> configuration subcommands
│   ├── data - 🗄 <d> Backup and retrieve configuration files and directories to/from cloud storage using rclone.
│   ├── self - 🔄 <s> self operations subcommands
│   ├── network - 🔐 <n> Network subcommands
│   └── execute - 🚀 <e> Execute python/shell scripts from pre-defined directories or as command
├── cloud - ☁ Cloud management commands
├── sessions - Layouts management subcommands
├── agents - 🤖 AI Agents management subcommands
├── utils - ⚙ utilities operations
├── fire - <f> Fire and manage jobs
└── croshell - <r> Cross-shell command execution

dot¶

Export the graph as Graphviz DOT text.

devops self explore dot [OPTIONS]

Key options from current help:

Option	Description
`--output`, `-o`	Write DOT output to a file
`--include-help`	Include help text in labels
`--max-depth`, `-d`	Limit the exported depth

Example:

devops self explore dot --max-depth 2

Representative output:

digraph cli_graph {
  graph [rankdir=LR, splines=true, bgcolor="white"];
  node [shape=box, style="rounded,filled", fontname="Helvetica", fontsize=10, color="#333333"];
  edge [color="#999999"];
  "mcfg" [label="mcfg\nMachineConfig CLI - Manage your machine configurations and workflows", shape="doubleoctagon", fillcolor="#f1f1f1", color="#555555"];
  "mcfg devops" [label="devops\n🔧 DevOps operations", shape="box", fillcolor="#dbeafe", color="#2563eb"];
  "mcfg" -> "mcfg devops";
  "mcfg devops self" [label="self\n🔄 <s> self operations subcommands", shape="box", fillcolor="#dbeafe", color="#2563eb"];
  "mcfg devops" -> "mcfg devops self";
}

sunburst¶

Render the graph as a Plotly sunburst view.

devops self explore sunburst [OPTIONS]

Key options from current help:

Option	Description
`--output`, `-o`	Write HTML or image output
`--max-depth`, `-d`	Limit the exported depth
`--template`	Plotly template name
`--height`	Static image height
`--width`	Static image width

Example:

devops self explore sunburst --output docs/assets/devops-self-explore/sunburst.html --template plotly_dark

Standalone HTML result: sunburst.html

treemap¶

Render the graph as a Plotly treemap view.

devops self explore treemap [OPTIONS]

The option set matches sunburst: --output, --max-depth, --template, --height, and --width.

Example:

devops self explore treemap --output docs/assets/devops-self-explore/treemap.html --template plotly_dark

Standalone HTML result: treemap.html

icicle¶

Render the graph as a Plotly icicle view.

devops self explore icicle [OPTIONS]

The option set matches sunburst: --output, --max-depth, --template, --height, and --width.

Example:

devops self explore icicle --output docs/assets/devops-self-explore/icicle.html --template plotly_dark

Standalone HTML result: icicle.html

tui¶

Open the full-screen Textual navigator.

devops self explore tui

Interactive controls:

/ focuses search
c copies the selected command
r runs the selected command
b builds the selected command with arguments
? opens in-app help
q quits

No static screenshot is checked into the docs for the TUI. Launch it locally to inspect the current command tree.

build-docker¶

Build the repo Docker image variants through the checked-in shell wrapper.

devops self build-docker [VARIANT]

Supported variants from current help:

Variant	Meaning
`slim`	Build the slim image
`ai`	Build the AI-oriented image

Example:

devops self build-docker ai

This command is only registered when ~/code/machineconfig exists locally.

security¶

Security helpers live under a nested Typer app:

devops self security [SUBCOMMAND] [ARGS]...

Current devops self security --help exposes:

Command	Description
`scan`	Scan installed apps or a single file with VirusTotal
`list`	List installed apps, optionally filtered by name
`upload`	Upload a local file to the project cloud storage
`download`	Download a file from Google Drive
`install`	Install safe apps from the saved app metadata report
`repo-licenses`	Download GitHub repo license files for installer entries
`report`	Inspect saved scan reports, raw rows, or summary statistics

scan¶

Scan installed apps or one local file path with VirusTotal.

devops self security scan [OPTIONS] [APPS]

Key options from current help:

Option	Description
`APPS`	Optional comma-separated app names to scan
`--path`	Scan one explicit file path instead of installed apps
`--record`, `--no-record`	Control whether the result is saved into the repo reports

Examples:

devops self security scan
devops self security scan git,uv
devops self security scan --path ./downloads/tool.exe --no-record

list¶

List the installed CLI apps that the security tooling knows how to inspect.

devops self security list [APPS]

Example:

devops self security list git,uv

upload¶

Upload one local file into the cloud storage used by the security workflow.

devops self security upload PATH

Example:

devops self security upload ./dist/tool.exe

download¶

Download a previously shared file from Google Drive.

devops self security download URL

The argument can be a full Google Drive URL or a raw file id.

install¶

Install a safe app from the saved metadata report.

devops self security install NAME

NAME can be one app entry from the report or the special essentials bundle.

repo-licenses¶

Download GitHub license files for repos referenced by the installer metadata.

devops self security repo-licenses [OPTIONS]

Key option:

Option	Description
`--github-token`	GitHub token, also read from `MACHINECONFIG_GITHUB_TOKEN`, `GITHUB_TOKEN`, or `GH_TOKEN`

report¶

Inspect saved report data in full, summary, table, or CSV form. The default invocation shows the full engine-level report.

devops self security report [OPTIONS] [APPS]

Key options from current help:

Option	Description
`APPS`	Optional comma-separated app names to filter on
`--view`, `-v`	Choose `engines`, `app-summary`, `apps`, `options`, or `stats`
`--format`, `-f`	Choose `table` or `csv` output for the raw `apps` and `engines` views

Examples:

devops self security report
devops self security report --view app-summary
devops self security report --view stats
devops self security report uv --view apps --format csv
devops self security report git --view engines

This command is only registered when ~/code/machineconfig exists locally.

docs¶

Serve the local docs preview and print the localhost and LAN URLs.

devops self docs [OPTIONS]

Key options:

Option	Description
`--rebuild`, `-b`	Rebuild the docs before starting the preview server
`--create-artifacts`, `-a`	Regenerate the Plotly CLI graph HTML artifacts before serving

Current behavior:

Prints http://127.0.0.1:8000/machineconfig/ and, when available, the LAN preview URL.
With --rebuild, syncs the changelog and runs zensical build before zensical serve.
With --create-artifacts, refreshes the checked-in CLI graph HTML exports under docs/assets/devops-self-explore/.
Serves on 0.0.0.0:8000.

Examples:

devops self docs
devops self docs --rebuild
devops self docs --rebuild --create-artifacts

assets¶

Regenerate the checked-in CLI graph JSON and chart artifacts from the local repo checkout.

devops self assets [SUBCOMMAND] [ARGS]...

Current devops self assets --help exposes:

Command	Description
`update-cli-graph`	Rewrite `src/machineconfig/scripts/python/graph/cli_graph.json` from the current Typer source
`regenerate-charts`	Rewrite `docs/assets/devops-self-explore/sunburst.html` from the current graph snapshot

Examples:

devops self assets update-cli-graph
devops self assets regenerate-charts

This sub-app is only registered when ~/code/machineconfig exists locally.

readme¶

Fetch the project README from GitHub and render it as rich Markdown in the terminal.

devops self readme

This is useful when the repo checkout is not open locally but you still want the current upstream README rendered in the terminal.

network¶

Network management.

devops network [SUBCOMMAND] [ARGS]...

Network configuration, sharing, SSH setup, device-focused WiFi/WARP/WSL helpers, and VS Code tunneling.

Current devops network --help exposes:

Command	Description
`share-terminal`	Share a terminal in the browser
`share-server`	Start a local or internet-facing file server
`send`	Send files or text from the current machine
`receive`	Receive files or text using a transfer code
`share-temp-file`	Upload one file to `temp.sh`
`ssh`	SSH server, key, and debugging subcommands
`device`	Device-oriented WiFi, WARP, and WSL subcommands
`show-address`	Show local and public addresses
`vscode-share`	Share a workspace with VS Code Tunnels or serve-web

Share a terminal through the browser.

devops network share-terminal [OPTIONS]

Key options from current help:

Option	Description
`--port`, `-p`	Port for the terminal server
`--username`, `-u`	Login username
`--password`, `-w`	Login password
`--no-auth`, `-n`	Disable authentication
`--start-command`, `-s`	Command to start in the shared terminal
`--ssl`, `-S`	Enable SSL
`--ssl-cert`, `-C`	Certificate file path
`--ssl-key`, `-K`	Key file path
`--ssl-ca`, `-A`	CA file for client certificate verification
`--over-internet`, `-i`	Expose via ngrok
`--install-dep`, `-D`	Install missing dependencies

Example:

devops network share-terminal --port 7681

Start a local or internet-facing file browser or static share server.

devops network share-server PATH [OPTIONS]

Key options from current help:

Option	Description
`--port`, `-p`	Port for the share server
`--username`, `-u`	Login username
`--password`, `-w`	Login password
`--no-auth`, `-na`	Disable authentication
`--bind`, `-a`	Bind address
`--over-internet`, `-i`	Expose via ngrok
`--backend`, `-b`	Backend choice from `filebrowser`, `miniserve`, `qrcp`, or `easy-sharing`
`--install-dep`, `-D`	Install missing dependencies

Example:

devops network share-server ~/Downloads --backend miniserve --port 8080

send¶

Send a file, directory, or text payload.

devops network send PATH [OPTIONS]

Key options from current help:

Option	Description
`--zip`	Zip the folder before sending
`--code`, `-c`	Explicit relay codephrase
`--text`, `-t`	Send text instead of file contents
`--qrcode`, `--qr`	Show the receive code as a QR code
`--backend`, `-b`	Transfer backend: `wormhole` or `croc`
`--install-dep`, `-D`	Install missing dependencies

Examples:

devops network send ./build/output.zip
devops network send . --zip --backend wormhole

receive¶

Receive files or text using a codephrase or explicit relay arguments.

devops network receive CODE_ARGS... [OPTIONS]

The argument may be a plain receive code such as 7121-donor-olympic-bicycle or a full relay invocation such as --relay 10.17.62.206:443 7121-donor-olympic-bicycle.

Example:

devops network receive 7121-donor-olympic-bicycle

Upload one file to temp.sh.

devops network share-temp-file FILE_PATH

Example:

devops network share-temp-file ./report.txt

ssh¶

SSH setup and troubleshooting lives under a nested Typer app:

devops network ssh [SUBCOMMAND] [ARGS]...

devops network ssh --help currently exposes:

Command	Description
`install-server`	Install the SSH server
`change-port`	Change the SSH port on Linux or WSL
`add-key`	Add an SSH public key locally or remotely
`debug`	Run SSH diagnostics

install-server¶

devops network ssh install-server

Installs and configures the platform SSH server.

change-port¶

devops network ssh change-port --port 2222

Key option:

Option	Description
`--port`, `-p`	SSH port to use

add-key¶

devops network ssh add-key [OPTIONS]

Key options from current help:

Option	Description
`--path`	Path to a public key file
`--choose`, `-c`	Choose from `~/.ssh/*.pub`
`--value`, `-v`	Paste the public key manually
`--github`, `-g`	Pull public keys from a GitHub username
`--remote`, `-r`	Deploy the key to a remote machine

Examples:

devops network ssh add-key --choose
devops network ssh add-key --github thisismygitrepo
devops network ssh add-key --path ~/.ssh/id_ed25519.pub --remote myhost

debug¶

devops network ssh debug

Runs platform-specific SSH debugging helpers.

device¶

Device-specific network actions now live under a nested Typer app:

devops network device [SUBCOMMAND] [ARGS]...

devops network device --help currently exposes:

Command	Description
`switch-public-ip`	Switch the public IP through Cloudflare WARP
`wifi-select`	Connect using configured or manually selected WiFi
`bind-wsl-port`	Bind a WSL port onto the Windows host
`open-wsl-port`	Open Windows Firewall rules for WSL ports
`link-wsl-windows`	Link WSL home and Windows home directories
`reset-cloudflare-tunnel`	Reconfigure Cloudflare tunnel execution
`add-ip-exclusion-to-warp`	Add WARP tunnel exclusions

show-address¶

Show local interface addresses plus the public IP address when available.

devops network show-address

Example:

devops network show-address

switch-public-ip¶

Switch the public IP through Cloudflare WARP.

devops network device switch-public-ip [OPTIONS]

Key options from current help:

Option	Description
`--wait`, `-w`	Seconds to wait between steps
`--max-trials`, `-m`	Maximum number of switch attempts
`--target-ip`, `-t`	Acceptable target IPs that skip the switch if already active

Example:

devops network device switch-public-ip --max-trials 5 --target-ip 203.0.113.10

wifi-select¶

Connect to WiFi using the configured SSID or an interactive fallback flow.

devops network device wifi-select [OPTIONS]

Key options from current help:

Option	Description
`--ssid`, `-n`	Configured SSID to try first
`--manual`, `-m`	Jump directly to manual selection
`--list`, `-l`	Only list visible networks

Examples:

devops network device wifi-select --list
devops network device wifi-select --manual

bind-wsl-port¶

Bind a WSL port onto the Windows host using netsh interface portproxy.

devops network device bind-wsl-port --port 8080

open-wsl-port¶

Open Windows Firewall rules for one or more WSL ports.

devops network device open-wsl-port 8080,3000-3005,443

link-wsl-windows¶

Link WSL home and Windows home directories.

devops network device link-wsl-windows [OPTIONS]

Key option:

Option	Description
`--windows-username`, `-u`	Override the auto-detected Windows username

reset-cloudflare-tunnel¶

Print or run the commands needed to reconfigure Cloudflare tunnel execution.

devops network device reset-cloudflare-tunnel [OPTIONS]

Key options from current help:

Option	Description
`--task`, `-t`	Required mode: `oneoff-shell-process`, `oneoff-background-process`, or `as-service`
`--tunnel-name`, `-n`	Tunnel name for one-off modes

Examples:

devops network device reset-cloudflare-tunnel --task oneoff-shell-process --tunnel-name my-tunnel
devops network device reset-cloudflare-tunnel --task as-service

add-ip-exclusion-to-warp¶

Add one or more IP exclusions to Cloudflare WARP.

devops network device add-ip-exclusion-to-warp --ip 192.168.20.25,10.0.0.15

Generate or run VS Code Tunnel and code serve-web commands.

devops network vscode-share ACTION [OPTIONS]

Supported actions from current help:

run
install-service
uninstall-service
share-local

Key options from current help:

Option	Description
`--name`, `-n`	Tunnel or service name
`--path`, `-p`	Server base path for `share-local`
`--host`, `-h`	Host for `share-local`
`--dir`, `-d`	Folder to open in `share-local` mode
`--extra-args`, `-e`	Extra CLI arguments to append

Examples:

devops network vscode-share run --name labbox
devops network vscode-share install-service --name labbox
devops network vscode-share share-local --dir . --host 0.0.0.0

The nested help screens render shortened usage such as devops share-server ..., devops ssh ..., devops device ..., or devops vscode-share ..., but the full entrypoints remain under devops network ....

execute¶

Execute Python or shell scripts from pre-defined directories.

devops execute [OPTIONS] [NAME]

Options¶

Option	Short	Description
`--where`	`-w`	Script location: `all`, `private`, `public`, `library`, `dynamic`, `custom`
`--interactive`	`-i`	Interactive selection of scripts
`--command`	`-c`	Run as command
`--list`	`-l`	List available scripts

Examples¶

# Run a script by name
devops execute my_script

# List all available scripts
devops execute --list
devops e -l

# Interactive script selection
devops execute --interactive
devops e -i

# Run from specific location
devops execute my_script --where private

devops¶

Usage¶

Commands Overview¶

install¶

Arguments¶

Options¶

Installation Modes¶

Single Package¶

Multiple Packages¶

Package Groups¶

Interactive Mode¶

From GitHub URL¶

From Binary URL¶

Available Package Groups¶

Listing Available Groups¶

Examples¶

repos¶

sync¶

register¶

action¶

analyze¶

guard¶

viz¶

count-lines¶

config-linters¶

cleanup¶

config¶

sync¶

register¶

edit¶

export-dotfiles¶

import-dotfiles¶

copy-assets¶

dump¶

terminal¶

data¶

sync¶

register¶

edit¶

Backup File Layout¶

self¶

update¶

init¶

status¶

install¶

explore¶

search¶

tree¶

dot¶

sunburst¶

treemap¶

icicle¶

tui¶

build-docker¶

security¶

scan¶

list¶

upload¶

download¶

install¶

repo-licenses¶

report¶

docs¶

assets¶

readme¶

network¶

share-terminal¶

share-server¶

send¶

receive¶

share-temp-file¶

ssh¶

install-server¶

change-port¶

add-key¶

debug¶

device¶

show-address¶

switch-public-ip¶

wifi-select¶