CLI Reference

Complete reference for all blackdot commands, options, and environment variables.

Quick Reference

blackdot status          # Visual dashboard
blackdot doctor          # Health check
blackdot doctor --fix    # Auto-fix issues
blackdot sync            # Smart bidirectional vault sync
blackdot vault pull      # Pull secrets from vault
blackdot vault push      # Push local changes to vault
blackdot template init   # Setup machine-specific configs
blackdot encrypt init    # Initialize age encryption
blackdot help            # Show all commands

The `blackdot` Command

The unified command for managing your blackdot configuration. All subcommands are accessed via blackdot <command>.

Command Overview

Command	Alias	Description
`status`	`s`	Quick visual dashboard
`doctor`	`health`	Comprehensive health check
`features`	`feat`	Feature Registry - enable/disable optional features
`hook`	-	Hook System - manage lifecycle hooks
`config`	`cfg`	Configuration Layers - view layered config
`drift`	-	Compare local files vs vault
`sync`	-	Bidirectional vault sync (smart push/pull)
`diff`	-	Preview changes before sync/restore
`backup`	-	Backup and restore configuration
`vault`	-	Secret vault operations
`template`	`tmpl`	Machine-specific config templates
`encrypt`	-	Age Encryption - encrypt sensitive files
`lint`	-	Comprehensive linter (shell, Go, JSON, YAML, PowerShell)
`migrate`	-	Migrate legacy config formats (INI→JSON)
`packages`	`pkg`	Check/install Brewfile packages
`metrics`	-	Visualize health check metrics over time
`setup`	-	Interactive setup wizard
`macos`	-	macOS system settings (macOS only)
`devcontainer`	`dc`	Generate devcontainer configurations
`upgrade`	`update`	Pull latest and run bootstrap
`uninstall`	-	Remove blackdot configuration
`cd`	-	Change to blackdot directory
`edit`	-	Open blackdot in $EDITOR
`help`	`-h`, `--help`	Show help

Status & Health Commands

`blackdot status`

Display a visual dashboard showing the current state of your blackdot configuration.

blackdot status
blackdot s              # Alias

Output includes:

Symlink status (zshrc, claude, /workspace)
SSH agent status (keys loaded)
AWS authentication status
Lima VM status (macOS only)
Suggested fixes for any issues

`blackdot doctor`

Run a comprehensive health check on your blackdot installation.

blackdot doctor [OPTIONS]
blackdot health         # Alias

Options:

Option	Short	Description
`--fix`	`-f`	Auto-fix permission issues
`--quick`	`-q`	Run quick checks only (skip vault)
`--help`	`-h`	Show help

Examples:

blackdot doctor              # Full health check
blackdot doctor --fix        # Auto-repair permissions
blackdot doctor --quick      # Fast checks (skip vault status)

Checks performed:

Version and update status
Symlinks (zshrc, p10k, claude, /workspace)
Required commands (zsh, git, brew, jq)
SSH keys and permissions (600 for private, 644 for public)
AWS configuration and credentials
Vault login status (unless --quick)
Shell configuration
Template system status

Exit codes:

0 - All checks passed
1 - One or more checks failed

Feature Management

`blackdot features`

Central registry for managing optional features. Enable, disable, and query the status of all optional blackdot functionality.

blackdot features [COMMAND] [OPTIONS]
blackdot feat               # Alias

Commands:

Command	Description
`list`	List all features and their status (default)
`status [feature]`	Show status for one or all features
`enable <feature>`	Enable a feature
`disable <feature>`	Disable a feature
`preset <name>`	Enable a preset (group of features)
`check <feature>`	Check if feature is enabled (for scripts)
`help`	Show help

List Options:

Option	Short	Description
`--all`	`-a`	Show dependencies
`--json`	`-j`	Output as JSON
`--category`	`-c`	Filter by category (core, optional, integration)

Enable/Disable Options:

Option	Short	Description
`--persist`	`-p`	Save to config file (survives shell restart)

Preset Options:

Option	Short	Description
`--list`	`-l`	List available presets
`--persist`	`-p`	Save all preset features to config file

Available Presets:

Preset	Features
`minimal`	`shell`, `config_layers`
`developer`	`shell`, `vault`, `aws_helpers`, `cdk_tools`, `rust_tools`, `go_tools`, `python_tools`, `ssh_tools`, `docker_tools`, `nvm_integration`, `sdkman_integration`, `git_hooks`, `modern_cli`, `config_layers`
`claude`	`shell`, `workspace_symlink`, `claude_integration`, `vault`, `git_hooks`, `modern_cli`, `config_layers`
`full`	All features

Examples:

# List all features with status
blackdot features
blackdot features list

# Filter by category
blackdot features list optional
blackdot features list integration

# Show with dependencies
blackdot features list --all

# JSON output (for scripting)
blackdot features list --json

# Enable a feature (runtime only)
blackdot features enable vault

# Enable and persist to config file
blackdot features enable vault --persist

# Disable a feature
blackdot features disable health_metrics

# Enable a preset
blackdot features preset developer --persist

# List available presets
blackdot features preset --list

# Check if feature enabled (for scripts)
if blackdot features check vault; then
    blackdot vault pull
fi

Feature Categories:

Category	Description
`core`	Always enabled (shell)
`optional`	Optional features (vault, templates, etc.)
`integration`	Third-party tool integrations (nvm, sdkman, etc.)

Environment Variable Control:

Features can also be controlled via environment variables:

# SKIP_* variables (backward compatible)
SKIP_WORKSPACE_SYMLINK=true    # Disables workspace_symlink
SKIP_CLAUDE_SETUP=true         # Disables claude_integration
BLACKDOT_SKIP_DRIFT_CHECK=1    # Disables drift_check

# Direct feature control
BLACKDOT_FEATURE_VAULT=true    # Enable vault
BLACKDOT_FEATURE_VAULT=false   # Disable vault

See also: Feature Registry for complete documentation.

Hook Commands

`blackdot hook`

Manage lifecycle hooks for custom behavior at key points.

blackdot hook [COMMAND] [OPTIONS] [HOOK_POINT]

Commands:

Command	Description
`list`	List all hook points or hooks for a specific point
`run`	Execute hooks for a hook point
`test`	Test hooks (shows what would run, then executes)

Options:

Option	Description
`--verbose`	Show detailed execution output
`--no-hooks`	Skip hook execution (for debugging)

Examples:

# List all hook points
blackdot hook list

# List hooks for a specific point
blackdot hook list post_vault_pull

# Run hooks for a point
blackdot hook run post_vault_pull

# Run with verbose output
blackdot hook run --verbose shell_init

# Test hooks (dry-run + execute)
blackdot hook test doctor_check

Hook Points

Category	Hook Points
Lifecycle	`pre_install`, `post_install`, `pre_bootstrap`, `post_bootstrap`, `pre_upgrade`, `post_upgrade`
Vault	`pre_vault_pull`, `post_vault_pull`, `pre_vault_push`, `post_vault_push`
Doctor	`pre_doctor`, `post_doctor`, `doctor_check`
Shell	`shell_init`, `shell_exit`, `directory_change`
Setup	`pre_setup_phase`, `post_setup_phase`, `setup_complete`

Creating Hooks

File-based hooks (recommended):

# Create hook directory
mkdir -p ~/.config/blackdot/hooks/post_vault_pull

# Create executable script
cat > ~/.config/blackdot/hooks/post_vault_pull/10-fix-perms.sh << 'EOF'
#!/bin/bash
chmod 600 ~/.ssh/id_* 2>/dev/null
EOF
chmod +x ~/.config/blackdot/hooks/post_vault_pull/10-fix-perms.sh

JSON-based hooks:

# Configure in hooks.json
cat > ~/.config/blackdot/hooks.json << 'EOF'
{
  "hooks": {
    "post_vault_pull": [
      {"name": "ssh-add", "command": "ssh-add ~/.ssh/id_ed25519", "enabled": true, "fail_ok": true}
    ]
  }
}
EOF

See also: Hook System for complete documentation.

Configuration Commands

`blackdot config`

View and manage configuration across all layers.

blackdot config [COMMAND] [OPTIONS]
blackdot cfg                # Alias

Commands:

Command	Description
`layers`	Show effective config with source layer for each setting
`get <key>`	Get a specific config value
`set <key> <value>`	Set a config value in user layer
`help`	Show help

Examples:

# Show all config with sources
blackdot config layers

# Output:
# vault.backend = bitwarden (user)
# vault.auto_sync = false (default)
# setup.completed = ["symlinks","packages"] (machine)

# Get specific value
blackdot config get vault.backend

# Set value in user config
blackdot config set vault.auto_backup true

Layer Priority (highest to lowest):

Priority	Layer	Source
1	Environment	`$BLACKDOT_*` variables
2	Project	`.blackdot.local` in current directory
3	Machine	`~/.config/blackdot/machine.json`
4	User	`~/.config/blackdot/config.json`
5	Defaults	Built-in fallbacks

`blackdot drift`

Compare local configuration files against vault to detect differences.

blackdot drift [OPTIONS]

Options:

Option	Short	Description
`--quick`	`-q`	Fast check against cached state (no vault access)
`--help`	`-h`	Show help

Modes:

Mode	Speed	Vault Access	Description
Full (default)	~2-5s	Required	Connects to vault, compares live vault content
Quick (`--quick`)	<50ms	Not required	Compares against cached checksums from last pull

Checks these items:

SSH-Config (~/.ssh/config)
AWS-Config (~/.aws/config)
AWS-Credentials (~/.aws/credentials)
Git-Config (~/.gitconfig)
Environment-Secrets (~/.local/env.secrets)
Template-Variables (~/.config/blackdot/template-variables.sh)

Output:

Shows which items are in sync
Shows which items have local changes
Suggests next steps (sync or restore)

Examples:

blackdot drift           # Full check (connects to vault)
blackdot drift --quick   # Fast check (local checksums only)

Shell Startup Integration:

Drift detection runs automatically on shell startup using quick mode. If local files have changed since your last vault pull, you'll see:

⚠ Drift detected: Git-Config Template-Variables
  Run: blackdot drift (to compare) or blackdot vault pull (to restore)

Disable with: export BLACKDOT_SKIP_DRIFT_CHECK=1

How it works:

After blackdot vault pull, checksums are saved to ~/.cache/blackdot/vault-state.json
On shell startup, local files are compared against cached checksums
If checksums differ, a warning is shown
Run full blackdot drift to compare against actual vault content

`blackdot sync`

Bidirectional sync between local files and vault. Intelligently determines sync direction based on what changed.

blackdot sync [OPTIONS] [ITEMS...]

Options:

Option	Short	Description
`--dry-run`	`-n`	Show what would be synced without making changes
`--force-local`	`-l`	Push all local changes to vault (overwrite vault)
`--force-vault`	`-v`	Pull all vault content to local (overwrite local)
`--verbose`	-	Show detailed comparison info (checksums)
`--all`	`-a`	Sync all syncable items
`--help`	`-h`	Show help

Sync Behavior:

By default, sync determines the correct direction for each item:

Condition	Action
Local changed since last sync	Push to vault
Vault changed since last sync	Pull from vault
Both changed	Conflict - requires `--force-*` flag
Neither changed	Skip (already in sync)

Conflict Resolution:

When both local and vault have changed since last sync:

blackdot sync --force-local   # Push local changes, overwrite vault
blackdot sync --force-vault   # Pull vault changes, overwrite local

Syncable Items:

SSH-Config (~/.ssh/config)
AWS-Config (~/.aws/config)
AWS-Credentials (~/.aws/credentials)
Git-Config (~/.gitconfig)
Environment-Secrets (~/.local/env.secrets)
Template-Variables (~/.config/blackdot/template-variables.sh)
Claude-Profiles (~/.claude/profiles.json)

Examples:

blackdot sync                     # Smart sync all items
blackdot sync --dry-run           # Preview what would be synced
blackdot sync Git-Config          # Sync single item
blackdot sync --force-local       # Push all local to vault
blackdot sync --force-vault       # Pull all vault to local
blackdot sync --verbose           # Show checksum details

How it works:

Loads cached checksums from ~/.cache/blackdot/vault-state.json (baseline from last sync)
Calculates current checksums for local files
Fetches vault content and calculates checksums
Compares each against baseline to determine which side changed
Performs push/pull operations based on detected changes
Updates drift state after successful sync

Exit Codes:

0 - All items synced successfully
1 - One or more items failed to sync
2 - Conflicts detected (use --force-* to resolve)

`blackdot diff`

Preview differences between local files and vault before performing sync or restore operations.

blackdot diff [OPTIONS] [ITEM]

Options:

Option	Short	Description
`--sync`	`-s`	Preview what sync would push to vault
`--restore`	`-r`	Preview what restore would change locally
`--help`	`-h`	Show help

Arguments:

Argument	Description
`ITEM`	Show diff for specific item (e.g., `SSH-Config`)

Examples:

blackdot diff                 # Show all differences
blackdot diff --sync          # What would be pushed to vault
blackdot diff --restore       # What would be restored locally
blackdot diff SSH-Config      # Diff specific item

Backup & Restore

`blackdot backup`

Create timestamped backups of configuration files or restore from previous backups.

blackdot backup [COMMAND] [OPTIONS]

Commands:

Command	Description
(none)	Create new backup
`--list`, `-l`, `list`	List available backups
`restore [ID]`	Restore from backup (latest if no ID)
`--help`, `-h`, `help`	Show help

Examples:

blackdot backup              # Create new backup
blackdot backup --list       # List available backups
blackdot backup restore      # Restore from latest backup
blackdot backup restore backup-20240115-143022  # Restore specific

Files backed up:

~/.ssh/config
~/.ssh/known_hosts
~/.gitconfig
~/.aws/config
~/.aws/credentials
~/.local/env.secrets
~/.zshrc
~/.p10k.zsh

Storage:

Backups stored in ~/.blackdot-backups/
Maximum 10 backups retained (oldest auto-deleted)
Each backup includes a manifest with metadata

`blackdot migrate`

Configuration Migration - Migrate legacy configuration formats to JSON.

blackdot migrate [OPTIONS]

What it migrates:

Config format: config.ini → config.json
Vault schema: Legacy format → current secrets[] array format
Preserves vault backend settings and setup state

Options:

Option	Description
`-y`, `--yes`	Skip confirmation prompt
`-h`, `--help`	Show help

Examples:

blackdot migrate              # Interactive migration with confirmation
blackdot migrate --yes        # Skip confirmation, migrate immediately

Safety:

Creates timestamped backups before migration
Idempotent - safe to run multiple times
Automatically detects if migration is needed

Vault Commands

`blackdot vault`

Manage secrets stored in your vault. Supports multiple backends with a unified interface.

blackdot vault <command> [OPTIONS]

Subcommands:

Command	Description
`init`	Configure vault backend with location support (v2 wizard)
`pull`	Pull secrets from vault to local machine
`push`	Push local files to vault
`sync`	Bidirectional sync (smart push/pull based on changes)
`setup`	Interactive onboarding wizard (three modes: Existing/Fresh/Manual)
`list`	List vault items (supports location filtering)
`check`	Validate vault items exist
`validate`	Validate vault item schema
`create`	Create new vault item
`delete`	Delete vault item(s)
`help`	Show help

vault create

Create a new Secure Note item in the vault.

blackdot vault create <item-name> [content] [OPTIONS]

Options:

Option	Short	Description
`--dry-run`	`-n`	Preview without making changes
`--force`	`-f`	Overwrite if item already exists
`--file`		Read content from file instead of argument

Content Sources (in order of precedence):

Command line argument: blackdot vault create Name "content"
File: blackdot vault create Name --file ~/path/to/file
Stdin: echo "content" | blackdot vault create Name

Examples:

# Create from argument
blackdot vault create API-Key "sk-1234567890"

# Create from file
blackdot vault create SSH-Config --file ~/.ssh/config

# Create from stdin
cat ~/.gitconfig | blackdot vault create Git-Config

# Preview what would be created
blackdot vault create --dry-run Test-Item "preview content"

# Overwrite existing item
blackdot vault create --force API-Key "new-key"

vault delete

Delete one or more items from the vault.

blackdot vault delete <item-name>... [OPTIONS]

Options:

Option	Short	Description
`--dry-run`	`-n`	Preview without making changes
`--force`	`-f`	Skip confirmation prompts (except protected items)

Protected Items:

These items require typing the item name to confirm deletion, even with --force:

SSH-* - SSH keys and configs
AWS-* - AWS credentials
Git-Config - Git configuration
Environment-Secrets - Environment variables

Examples:

# Delete single item (with confirmation)
blackdot vault delete OLD-API-KEY

# Delete multiple items with force
blackdot vault delete --force TEMP-1 TEMP-2 TEMP-3

# Preview what would be deleted
blackdot vault delete --dry-run OLD-KEY

# Protected item requires typing name even with force
blackdot vault delete SSH-Work
# Type "SSH-Work" to confirm

Supported Backends

The vault system supports three backends with identical functionality:

Backend	CLI Tool	Description
Bitwarden	`bw`	Default. Cloud-synced, full-featured
1Password	`op`	v2 CLI with biometric auth on macOS
pass	`pass`	GPG-based, git-synced, local-first

Switching Backends

# Set backend in ~/.zshrc or ~/.zshenv
export BLACKDOT_VAULT_BACKEND=bitwarden  # (default)
export BLACKDOT_VAULT_BACKEND=1password
export BLACKDOT_VAULT_BACKEND=pass

All blackdot vault commands work identically regardless of backend.

Backend Setup

Bitwarden (default):

brew install bitwarden-cli
bw login
export BW_SESSION="$(bw unlock --raw)"

1Password:

brew install --cask 1password-cli
op signin
export BLACKDOT_VAULT_BACKEND=1password
export ONEPASSWORD_VAULT=Personal  # optional, default vault

pass:

brew install pass
pass init <gpg-key-id>
export BLACKDOT_VAULT_BACKEND=pass
export PASS_PREFIX=blackdot  # optional, items stored as blackdot/Git-Config

Location Management

Vault items can be organized by location (folder, vault, directory) depending on your backend:

Backend	Location Type	Example
Bitwarden	`folder`	Items in "blackdot" folder
1Password	`vault` or `tag`	Items in "Personal" vault (planned)
pass	`directory`	Items in `blackdot/` prefix directory

Configuration in vault-items.json:

{
  "vault_location": {
    "type": "folder",
    "value": "blackdot"
  },
  "vault_items": { ... }
}

Location types:

folder - Bitwarden folders
vault - 1Password vaults (planned)
tag - 1Password tags (planned)
directory - pass directories/prefixes
prefix - Name-based prefix filtering
none - No location filtering (legacy behavior)

The setup wizard (blackdot vault init) guides you through selecting or creating a location.

Configuration File

Vault items are defined in a user-editable JSON config:

~/.config/blackdot/vault-items.json

Setup:

# Copy example and customize
mkdir -p ~/.config/blackdot
cp vault/vault-items.example.json ~/.config/blackdot/vault-items.json
$EDITOR ~/.config/blackdot/vault-items.json

# Or use the setup wizard
blackdot setup

Example Managed Items

Define your items in the config file. Example structure:

Item Name	Local Path	Type
`SSH-GitHub`	`~/.ssh/id_ed25519_github`	SSH key
`SSH-Work`	`~/.ssh/id_ed25519_work`	SSH key
`SSH-Config`	`~/.ssh/config`	Config file
`AWS-Config`	`~/.aws/config`	Config file
`AWS-Credentials`	`~/.aws/credentials`	Config file
`Git-Config`	`~/.gitconfig`	Config file
`Environment-Secrets`	`~/.local/env.secrets`	Config file (optional)

`blackdot vault pull`

Pull secrets from vault to local machine.

blackdot vault pull [OPTIONS]

Options:

Option	Short	Description
`--force`	`-f`	Skip drift check, overwrite local changes

Behavior:

Creates auto-backup of existing files
Checks for local drift (unless --force)
Syncs vault to get latest
Pulls SSH keys, AWS config, Git config, etc.
Sets correct file permissions

Environment variables:

BLACKDOT_SKIP_DRIFT_CHECK=1 - Skip drift check (for automation)

`blackdot vault push`

Push local configuration files to vault.

blackdot vault push [OPTIONS] [ITEMS...]

Options:

Option	Short	Description
`--dry-run`	`-n`	Show what would be pushed without making changes
`--all`	`-a`	Push all items
`--help`	`-h`	Show help

Arguments:

Argument	Description
`ITEMS`	Specific items to push (space-separated)

Pushable items:

SSH-Config
AWS-Config
AWS-Credentials
Git-Config
Environment-Secrets
Template-Variables

Examples:

blackdot vault push --all            # Push all items
blackdot vault push --dry-run --all  # Preview changes
blackdot vault push SSH-Config       # Push single item
blackdot vault push Git-Config AWS-Config  # Push multiple

`blackdot vault sync`

Bidirectional sync - intelligently determines whether to push or pull each item.

blackdot vault sync [OPTIONS] [ITEMS...]

Same as blackdot sync. See blackdot sync for full documentation.

Quick Examples:

blackdot vault sync                  # Smart sync all items
blackdot vault sync --dry-run        # Preview changes
blackdot vault sync --force-local    # Force push local to vault
blackdot vault sync --force-vault    # Force pull vault to local

`blackdot vault list`

List vault items managed by blackdot.

blackdot vault list

`blackdot vault check`

Validate that required vault items exist.

blackdot vault check

`blackdot vault validate`

Validate vault item schema (structure, content format).

blackdot vault validate

Validates:

SSH keys contain proper BEGIN/END markers
Config files have minimum content length
Items are correct type (secureNote)

Template Commands

`blackdot template`

Manage machine-specific configuration templates.

blackdot template <command> [OPTIONS]
blackdot tmpl <command>   # Alias

Subcommands:

Command	Alias	Description
`init`	-	Interactive setup wizard
`render`	-	Render templates to generated/
`check`	`validate`	Validate template syntax
`diff`	-	Show differences between templates and generated
`vars`	`variables`	List all template variables
`edit`	-	Open _variables.local.sh in editor
`link`	`symlink`	Create symlinks from generated files
`list`	`ls`	List available templates
`vault`	-	Sync template variables with vault
`help`	`-h`, `--help`	Show help

`blackdot template init`

Interactive setup wizard for the template system.

blackdot template init

What it does:

Detects system info (hostname, OS, architecture)
Creates templates/_variables.local.sh
Opens editor to customize variables

Vault Integration: Template variables can be stored in your vault for portable restoration across machines:

# Store in vault (current machine)
blackdot vault push Template-Variables

# Restore from vault (new machine)
blackdot vault pull
blackdot template render --all

Variables are stored at ~/.config/blackdot/template-variables.sh (XDG location).

`blackdot template render`

Render templates to the generated/ directory.

blackdot template render [OPTIONS] [FILE]

Options:

Option	Short	Description
`--dry-run`	`-n`	Show what would be done
`--force`	`-f`	Force re-render even if up to date
`--verbose`	`-v`	Show detailed output

Arguments:

Argument	Description
`FILE`	Render specific template only

Examples:

blackdot template render              # Render all templates
blackdot template render --dry-run    # Preview changes
blackdot template render gitconfig    # Render specific template

`blackdot template vars`

List all template variables and their current values.

blackdot template vars [OPTIONS]

Options:

Option	Short	Description
`--quiet`	`-q`	Minimal output (values only)

`blackdot template link`

Create symlinks from generated files to their destinations.

blackdot template link [OPTIONS]

Options:

Option	Short	Description
`--dry-run`	`-n`	Show what would be linked

Link destinations:

gitconfig -> ~/.gitconfig
99-local.zsh -> zsh/zsh.d/99-local.zsh
ssh-config -> ~/.ssh/config
claude.local -> ~/.claude.local

`blackdot template diff`

Show differences between templates and generated files.

blackdot template diff [OPTIONS]

Options:

Option	Short	Description
`--verbose`	`-v`	Show detailed diff output

`blackdot template list`

List available templates and their status.

blackdot template list
blackdot template ls    # Alias

Status indicators:

Up to date
Stale (needs re-rendering)
Not generated

`blackdot template vault`

Sync template variables (_variables.local.sh) with your vault for cross-machine portability.

blackdot template vault <command> [OPTIONS]

Subcommands:

Command	Description
`push`	Push local variables to vault
`pull`	Pull from vault to local file
`diff`	Show differences between local and vault
`sync`	Bidirectional sync with conflict detection
`status`	Show sync status (default)
`help`	Show help

Options:

Option	Short	Description
`--force`	`-f`	Force overwrite without confirmation
`--prefer-local`	-	On sync conflict, use local file
`--prefer-vault`	-	On sync conflict, use vault item
`--no-backup`	-	Don't backup local file on pull

Examples:

# Backup template variables to vault
blackdot template vault push

# Restore on new machine
blackdot template vault pull

# Check sync status
blackdot template vault status

# See differences
blackdot template vault diff

# Sync with conflict resolution
blackdot template vault sync --prefer-local

Vault Item: Template-Variables

Works with all vault backends (Bitwarden, 1Password, pass).

Encryption Commands

`blackdot encrypt`

Manage file encryption using the age tool. Encrypts sensitive files that aren't managed by vault (like template variables).

blackdot encrypt <command> [OPTIONS]

Subcommands:

Command	Description
`init`	Initialize encryption (generate age key pair)
`encrypt <file>`	Encrypt a file (creates `.age` file, removes original)
`decrypt <file>`	Decrypt a `.age` file
`edit <file>`	Decrypt, open in $EDITOR, re-encrypt on save
`list`	List encrypted and unencrypted sensitive files
`status`	Show encryption status and key info
`push-key`	Push private key to vault for backup/recovery
`help`	Show help

Options:

Option	Short	Description
`--keep`	`-k`	Keep original file when encrypting/decrypting
`--force`	`-f`	Force operation (e.g., regenerate keys)
`--dry-run`	`-n`	Show what would be done

`blackdot encrypt init`

Initialize age encryption by generating a new key pair.

blackdot encrypt init [--force]

What it creates:

~/.config/blackdot/age-key.txt - Private key (mode 600)
~/.config/blackdot/age-recipients.txt - Public key

Example:

blackdot encrypt init          # Generate new key pair
blackdot encrypt init --force  # Regenerate keys (WARNING: loses access to encrypted files)

`blackdot encrypt <file>`

Encrypt a file using age.

blackdot encrypt <file> [--keep]

Behavior:

Encrypts file to <file>.age
Removes original file (unless --keep)
The .age file can be committed to git

Examples:

# Encrypt template variables
blackdot encrypt templates/_variables.local.sh

# Keep original file
blackdot encrypt templates/_arrays.local.json --keep

# Preview
blackdot encrypt templates/_variables.local.sh --dry-run

`blackdot encrypt decrypt <file>`

Decrypt an .age file.

blackdot encrypt decrypt <file.age> [--keep]

Behavior:

Decrypts <file>.age to <file>
Removes .age file (unless --keep)

Examples:

# Decrypt template variables
blackdot encrypt decrypt templates/_variables.local.sh.age

# Keep encrypted file
blackdot encrypt decrypt templates/_variables.local.sh.age --keep

`blackdot encrypt edit`

Edit an encrypted file in place.

blackdot encrypt edit <file>

Workflow:

Decrypts file to temporary location
Opens in $EDITOR
Re-encrypts on save

Example:

blackdot encrypt edit templates/_variables.local.sh.age

`blackdot encrypt list`

List encrypted files and files that should be encrypted.

blackdot encrypt list

Output shows:

Files already encrypted (.age files)
Sensitive files that should be encrypted (matching patterns like *.secret, _variables.local.sh)

`blackdot encrypt status`

Show encryption status and key information.

blackdot encrypt status

Output includes:

Whether age is installed
Key initialization status
Public key (safe to share)
Count of encrypted files

`blackdot encrypt push-key`

Push your private key to vault for backup and recovery on other machines.

blackdot encrypt push-key

Vault item: Age-Private-Key

Recovery on new machine:

blackdot vault pull        # Restores age key via post_vault_pull hook
blackdot encrypt status    # Verify key restored

Encryption + Hooks Integration

The encryption system integrates with blackdot hooks:

Hook	When	Action
`pre_template_render`	Before template rendering	Auto-decrypt `.age` files in templates/
`post_vault_pull`	After vault pull	Restore age key from vault if missing
`pre_encrypt`	Before encryption	Custom pre-encrypt logic
`post_decrypt`	After decryption	Custom post-decrypt logic

Example workflow:

# First machine: encrypt and commit
blackdot encrypt templates/_variables.local.sh
blackdot encrypt push-key
git add templates/_variables.local.sh.age
git commit -m "Add encrypted template vars"
git push

# New machine: clone and decrypt
git pull
blackdot vault pull          # Restores age key
blackdot template render     # Auto-decrypts via hook

When to Use Encryption vs Vault

Use Case	Solution
SSH keys, AWS credentials	Vault (remote storage, pull on demand)
Template variables (emails, signing keys)	Encryption (committed to git, encrypted)
Files that need to be in git	Encryption
Files that should never be in git	Vault

Key insight: Vault and encryption serve different purposes. Vault is for secrets that live remotely. Encryption is for secrets that live in your git repo.

Maintenance Commands

`blackdot lint`

Comprehensive linter for blackdot configuration and code.

blackdot lint [OPTIONS]

Options:

Option	Short	Description
`--fix`	`-f`	Show fix suggestions (requires shellcheck)
`--verbose`	`-v`	Show all files checked
`--help`	`-h`	Show help

Checks:

Category	What's Checked
ZSH syntax	`zsh/zsh.d/*.zsh`, `zshrc`, `p10k.zsh`
Bash syntax	`bootstrap/.sh`, `lib/.sh`
Go code	`go vet` (errors), `gofmt` (formatting)
JSON files	`packages.json`, `~/.config/blackdot/config.json`
YAML files	`.github/workflows/*.yml`
Brewfile tiers	All 3 tiers exist (Brewfile, .minimal, .enhanced)
PowerShell	`.psm1`, `.ps1` syntax (if `pwsh` available)
Shellcheck	Static analysis for shell scripts (if installed)

Examples:

blackdot lint              # Check all configs
blackdot lint --verbose    # Show all files checked
blackdot lint --fix        # Show shellcheck fix suggestions

Sample Output:

Blackdot Configuration Linter
==============================

→ Checking ZSH syntax...
→ Checking Bash syntax...
→ Checking Go code...
→ Validating JSON files...
→ Validating YAML files...
→ Checking Brewfile tiers...
→ Checking PowerShell syntax...

==============================
Files checked: 39
[OK] All checks passed!

`blackdot packages`

Check and install packages from Brewfile (Unix) or packages.json (Windows).

blackdot packages [OPTIONS]
blackdot pkg [OPTIONS]    # Alias

Options:

Option	Short	Description
`--check`	`-c`	Show what's missing from package manifest
`--install`	`-i`	Install missing packages
`--outdated`	`-o`	Show outdated packages
`--help`	`-h`	Show help

Examples:

blackdot packages              # Overview
blackdot packages --check      # Show missing packages
blackdot packages --install    # Install from Brewfile (Unix) or packages.json (Windows)
blackdot packages --outdated   # Show outdated

Package Manifests:

Unix (macOS/Linux): Brewfile with Homebrew
Windows: powershell/packages.json with winget

`blackdot upgrade`

Pull latest changes and run bootstrap.

blackdot upgrade
blackdot update          # Alias

What it does:

Pulls latest changes from current branch
Re-runs bootstrap to update symlinks
Updates Homebrew packages from Brewfile
Runs health check with --fix

`blackdot setup`

Interactive setup wizard with persistent state. Use this after bootstrap for guided configuration.

blackdot setup [OPTIONS]

Options:

Option	Short	Description
`--status`	`-s`	Show current setup progress only
`--reset`	`-r`	Reset state and re-run from beginning
`--help`	`-h`	Show help

Setup phases:

Symlinks - Creates shell configuration symlinks
Packages - Installs Homebrew packages from Brewfile
Vault - Selects and authenticates vault backend
Secrets - Restores SSH keys, AWS creds, Git config
Claude Code - Optionally installs dotclaude for profile management

Features:

Progress persistence - Saves state to ~/.config/blackdot/
Resume support - Continue where you left off if interrupted
State inference - Detects existing installations automatically

Vault backend support:

Bitwarden (bw) - Handles login + unlock flow
1Password (op) - Handles signin flow
pass - Checks GPG agent access
None - Skip vault, configure secrets manually

Examples:

blackdot setup              # Run interactive wizard
blackdot setup --status     # Check progress
blackdot setup --reset      # Start over

`blackdot uninstall`

Remove blackdot configuration.

blackdot uninstall [OPTIONS]

Options:

Option	Short	Description
`--dry-run`	`-n`	Show what would be removed
`--keep-secrets`	`-k`	Keep SSH keys and AWS credentials
`--help`	`-h`	Show help

Examples:

blackdot uninstall --dry-run        # Preview removal
blackdot uninstall --keep-secrets   # Remove but keep secrets
blackdot uninstall                  # Full removal (prompts)

`blackdot metrics`

Visualize health check metrics over time.

blackdot metrics [OPTIONS]

Options:

Option	Short	Description
`--summary`	`-s`	Summary view (default)
`--graph`	`-g`	ASCII graph of health score trend
`--all`	`-a`	Show all metrics entries

Examples:

blackdot metrics              # Summary
blackdot metrics --graph      # Trend visualization
blackdot metrics --all        # All entries

macOS Commands

`blackdot macos`

Manage macOS system preferences (macOS only).

blackdot macos <command>

Subcommands:

Command	Description
`apply`	Apply settings from `macos/settings.sh`
`preview`	Dry-run mode - show what would be changed
`discover`	Capture current macOS settings
`help`	Show help

`blackdot macos apply`

Apply macOS system preferences from settings.sh.

blackdot macos apply [OPTIONS]

Options:

Option	Description
`--backup`	Backup current settings before applying

Settings applied:

Trackpad (tap to click, tracking speed, three-finger drag)
Keyboard (fast key repeat, disable auto-correct)
Dock (auto-hide, size, no recent apps)
Finder (show extensions, hidden files, path bar)
Screenshots (location, format, no shadow)
Security (password on wake, disable crash reporter)

Example:

blackdot macos apply          # Apply all settings
blackdot macos apply --backup # Backup first, then apply

`blackdot macos preview`

Show what settings would be changed without making changes.

blackdot macos preview

Same as blackdot macos apply --dry-run.

`blackdot macos discover`

Discover and capture current macOS settings.

blackdot macos discover [OPTIONS]

Options:

Option	Description
`--snapshot`	Take a snapshot of current settings
`--diff`	Compare current settings to last snapshot
`--generate`	Generate `settings.sh` from current preferences
`--domain <name>`	Show settings for specific domain
`--list-domains`	List all preference domains
`--all`	Dump all tracked domains

Examples:

# Discover workflow
blackdot macos discover --snapshot   # Take snapshot
# Make changes in System Preferences
blackdot macos discover --diff       # See what changed
blackdot macos discover --generate   # Generate settings.sh

# Inspect specific domain
blackdot macos discover --domain com.apple.dock

Devcontainer Commands

`blackdot devcontainer`

Generate devcontainer configurations for VS Code, GitHub Codespaces, and DevPod.

blackdot devcontainer <command> [OPTIONS]
blackdot dc <command>    # Alias

Subcommands:

Command	Description
`init`	Generate a devcontainer.json for your project
`images`	List available base images
`help`	Show help

`blackdot devcontainer init`

Generate a devcontainer.json configuration file.

blackdot devcontainer init [OPTIONS]

Options:

Option	Short	Description
`--image`		Base image to use (e.g., go, rust, python, node)
`--preset`		Blackdot preset (minimal, developer, claude, full)
`--output`	`-o`	Output directory (default: .devcontainer)
`--force`	`-f`	Overwrite existing devcontainer.json
`--no-extensions`		Don't include VS Code extensions

Available Images:

Name	Image	Extensions
Go	`mcr.microsoft.com/devcontainers/go:1.23`	golang.go
Rust	`mcr.microsoft.com/devcontainers/rust:latest`	rust-analyzer
Python	`mcr.microsoft.com/devcontainers/python:3.13`	ms-python.python
Node	`mcr.microsoft.com/devcontainers/typescript-node:22`	dbaeumer.vscode-eslint
Java	`mcr.microsoft.com/devcontainers/java:21`	vscjava.vscode-java-pack
Ubuntu	`mcr.microsoft.com/devcontainers/base:ubuntu`	-
Alpine	`mcr.microsoft.com/devcontainers/base:alpine`	-

Available Presets:

Preset	Description
`minimal`	Shell configuration only
`developer`	Full development tools
`claude`	Claude Code integration with portable sessions
`full`	All features enabled

Examples:

# Generate Go devcontainer with developer preset
blackdot devcontainer init --image go --preset developer

# Generate Python container for Claude Code
blackdot devcontainer init --image python --preset claude

# Overwrite existing configuration
blackdot devcontainer init --image rust --force

# Custom output directory
blackdot devcontainer init --image node -o ./my-container

Generated Configuration:

The generated devcontainer.json includes:

Base image from Microsoft's devcontainer registry
Blackdot feature from ghcr.io/blackwell-systems/blackdot
SSH agent socket forwarding for git operations
VS Code extensions for the selected language
postStartCommand to run blackdot setup

SSH Agent Forwarding:

The generated configuration mounts your host's SSH agent socket into the container, enabling git operations with your SSH keys without copying private keys into the container.

`blackdot devcontainer images`

List all available devcontainer base images.

blackdot devcontainer images

Output:

Shows all supported images with their descriptions and included VS Code extensions.

Developer Tools

`blackdot tools`

Cross-platform developer tools accessible via the Go CLI. These provide consistent behavior across ZSH, PowerShell, and any shell.

blackdot tools <category> [command] [OPTIONS]

Categories:

Category	Description	Shell Alias
`ssh`	SSH key and connection management	`sshtools`
`aws`	AWS profile and authentication	`awstools`
`cdk`	AWS CDK development helpers	`cdktools`
`go`	Go development helpers	`gotools`
`rust`	Rust/Cargo development helpers	`rusttools`
`python`	Python/uv development helpers	`pythontools`
`docker`	Docker container management	`dockertools`
`claude`	Claude Code configuration	`claudetools`

Examples:

blackdot tools ssh status      # Show SSH status banner
blackdot tools docker ps       # List containers
blackdot tools aws who         # Show AWS identity
sshtools keys                  # List SSH keys (via alias)
dockertools clean              # Clean Docker (via alias)

SSH Tools

blackdot tools ssh [command]
sshtools [command]             # Alias

Commands:

Command	Description
`keys`	List all SSH keys with fingerprints
`gen`	Generate new ED25519 key pair
`list` / `hosts`	List configured SSH hosts (styled table)
`agent`	Show SSH agent status and loaded keys (styled table)
`fp`	Show fingerprint(s) in multiple formats
`copy`	Copy public key to remote host
`tunnel`	Create SSH port forward tunnel
`socks`	Create SOCKS5 proxy through SSH host
`status`	Show SSH status with banner
`load [key]`	Add key to SSH agent
`unload <key>`	Remove key from SSH agent
`clear`	Remove all keys from agent
`tunnels`	List active SSH connections
`add-host <name>`	Add new host to SSH config
`remove-host <name>`	Remove host from SSH config

Examples:

sshtools                       # Show status banner
sshtools keys                  # List keys with fingerprints
sshtools hosts                 # List configured hosts in table
sshtools agent                 # Show agent status with loaded keys
sshtools gen work              # Generate ~/.ssh/id_ed25519_work
sshtools load github           # Add github key to agent
sshtools tunnel myserver 8080  # Forward local:8080 to server:8080
sshtools add-host prod         # Add host to config
sshtools remove-host staging   # Remove host from config

Docker Tools

blackdot tools docker [command]
dockertools [command]          # Alias

Commands:

Command	Description
`ps`	List containers
`images`	List Docker images
`logs <container>`	Show container logs
`exec <container> <cmd>`	Execute command in container
`shell <container>`	Open shell in container
`stop <container>`	Stop containers
`start <container>`	Start containers
`restart <container>`	Restart containers
`rm <container>`	Remove containers
`rmi <image>`	Remove images
`build`	Build Docker image
`pull <image>`	Pull an image
`push <image>`	Push an image
`tag <src> <dst>`	Tag an image
`clean`	Remove stopped containers and dangling images
`prune`	System prune (clean all unused resources)
`stats`	Show container resource usage
`ip <container>`	Get container IP address
`env <container>`	Show container environment variables
`ports`	Show all container ports
`vols`	List Docker volumes
`nets`	List Docker networks
`inspect <container>`	Inspect container
`status`	Show Docker status banner

Compose Subcommands:

dockertools compose up         # Start services
dockertools compose down       # Stop services
dockertools compose logs       # Show logs
dockertools compose ps         # List services
dockertools compose build      # Build services
dockertools compose restart    # Restart services
dockertools compose exec       # Execute in service
dockertools compose pull       # Pull service images

CDK Tools

blackdot tools cdk [command]
cdktools [command]             # Alias

Commands:

Command	Description
`init`	Initialize new CDK project
`env`	Set CDK_DEFAULT_ACCOUNT/REGION from AWS profile
`env-clear`	Clear CDK environment variables
`outputs`	Show CloudFormation stack outputs
`context`	Show or clear CDK context
`status`	Show CDK status banner
`deploy [stacks]`	Deploy CDK stacks
`deploy-all`	Deploy all CDK stacks
`diff [stacks]`	Show CDK diff
`check [stacks]`	Diff then prompt to deploy
`hotswap [stacks]`	Hotswap deploy (fast Lambda/ECS updates)
`synth`	Synthesize CloudFormation templates
`list`	List CDK stacks
`destroy [stacks]`	Destroy CDK stacks
`bootstrap`	Bootstrap CDK in AWS account

Go Tools

blackdot tools go [command]
gotools [command]              # Alias

Commands:

Command	Description
`new <name>`	Create new Go project
`init`	Initialize go.mod in current directory
`test`	Run tests with coverage
`cover`	Run tests and open coverage report
`lint`	Run golangci-lint
`outdated`	Check for outdated dependencies
`update`	Update all dependencies
`build-all`	Build for all platforms
`bench [pattern]`	Run benchmarks
`info`	Show Go environment info
`status`	Show Go status banner

Rust Tools

blackdot tools rust [command]
rusttools [command]            # Alias

Commands:

Command	Description
`new <name>`	Create new Rust project
`update`	Update Rust toolchain
`switch <channel>`	Switch toolchain (stable/nightly)
`lint`	Run clippy
`fix`	Auto-fix clippy warnings
`outdated`	Check for outdated dependencies
`expand`	Expand macros
`info`	Show Rust environment info
`status`	Show Rust status banner
`tools-install`	Install common Rust dev tools

Python Tools

blackdot tools python [command]
pythontools [command]          # Alias
pytools [command]              # Alias

Commands:

Command	Description
`new <name>`	Create new Python project with uv
`clean`	Remove pycache and .pyc files
`venv`	Create/activate virtual environment
`test`	Run pytest
`cover`	Run tests with coverage
`info`	Show Python environment info
`status`	Show Python status banner

Navigation Commands

`blackdot cd`

Change to the blackdot directory.

blackdot cd

Equivalent to: cd ~/workspace/blackdot

`blackdot edit`

Open blackdot in your editor.

blackdot edit

Uses $EDITOR (defaults to vim).

Installer Script

`install.sh`

One-line installer for blackdot.

curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh | bash

Options:

Option	Short	Description
`--minimal`	`-m`	Skip optional features (vault, Claude setup)
`--ssh`	-	Clone using SSH instead of HTTPS
`--help`	`-h`	Show help

After installation:

Run blackdot setup for interactive configuration of vault, secrets, and Claude Code.

Examples:

# Default install (one-liner)
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh | bash

# Minimal mode (no vault, no Claude)
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh -o install.sh && bash install.sh --minimal

# Clone via SSH
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh -o install.sh && bash install.sh --ssh

Environment Variables

Bootstrap & Installation

Variable	Values	Description
`SKIP_WORKSPACE_SYMLINK`	`true`	Skip `/workspace` symlink creation
`SKIP_CLAUDE_SETUP`	`true`	Skip Claude Code configuration
`BREWFILE_TIER`	`minimal`	Install only essentials (18 packages, ~2 min)
`BREWFILE_TIER`	`enhanced`	Modern CLI tools without containers (43 packages, ~5 min) ← RECOMMENDED
`BREWFILE_TIER`	`full`	Everything including Docker/Node (61 packages, ~10 min) [default]

Note: The blackdot setup wizard now presents tier selection interactively. These environment variables are for advanced/automated setups.

Examples:

# Single-machine setup (no /workspace symlink)
SKIP_WORKSPACE_SYMLINK=true ./bootstrap/bootstrap-mac.sh

# Skip Claude integration
SKIP_CLAUDE_SETUP=true ./bootstrap/bootstrap-linux.sh

# Use minimal Brewfile tier (essentials only)
BREWFILE_TIER=minimal ./bootstrap/bootstrap-mac.sh

# Use enhanced tier (modern tools, no containers)
BREWFILE_TIER=enhanced ./bootstrap/bootstrap-linux.sh

# Combine flags
BREWFILE_TIER=enhanced SKIP_CLAUDE_SETUP=true ./bootstrap/bootstrap-mac.sh

Vault Operations

Variable	Values	Description
`BLACKDOT_VAULT_BACKEND`	`bitwarden`, `1password`, `pass`	Vault backend to use (default: `bitwarden`)
`BLACKDOT_OFFLINE`	`1`	Skip all vault operations
`BLACKDOT_SKIP_DRIFT_CHECK`	`1`	Skip drift check before restore
`BW_SESSION`	session token	Bitwarden session (set by `bw unlock`)
`ONEPASSWORD_VAULT`	vault name	1Password vault name (default: `Personal`)
`PASS_PREFIX`	prefix	Pass store prefix (default: `blackdot`)

Examples:

# Use 1Password instead of Bitwarden
export BLACKDOT_VAULT_BACKEND=1password

# Offline mode (air-gapped environments)
BLACKDOT_OFFLINE=1 ./bootstrap/bootstrap-linux.sh

# Force pull without drift check
BLACKDOT_SKIP_DRIFT_CHECK=1 blackdot vault pull

Template System

Variable	Values	Description
`BLACKDOT_TMPL_*`	any	Override any template variable
`BLACKDOT_MACHINE_TYPE`	`work`, `personal`	Force machine type detection
`DEBUG`	`1`	Enable debug output

Examples:

# Override git email for one render
BLACKDOT_TMPL_GIT_EMAIL="other@example.com" blackdot template render

# Force machine type
BLACKDOT_MACHINE_TYPE=work blackdot template render

# Debug template rendering
DEBUG=1 blackdot template render

Debug & Development

Variable	Values	Description
`DEBUG`	`1`	Enable debug output in vault and template operations
`BLACKDOT_DIR`	path	Override blackdot directory location

Shell Functions

These functions are available in your shell after setup.

Zsh (macOS/Linux): Loaded from zsh/zsh.d/*.zsh PowerShell (Windows): Loaded from Blackdot.psm1

Most functions work identically across shells.

`status`

Same as blackdot status. Visual dashboard.

status

`j`

Jump to any project by fuzzy search.

j [BASE_DIR]

Uses fzf to find git repositories under /workspace (or specified directory).

`note` / `notes`

Quick timestamped notes.

note "Your note text"     # Add a note
notes                      # View recent notes
notes all                  # View all notes
notes edit                 # Open notes file
notes search <term>        # Search notes

Notes stored in ~/workspace/.notes.md.

`blackdot upgrade`

Pull latest changes and run bootstrap.

blackdot upgrade
blackdot update    # Alias

Exit Codes

Most commands follow these conventions:

Code	Meaning
`0`	Success
`1`	Failure (check failed, item not found, etc.)

File Locations

File	Purpose
`~/workspace/blackdot/`	Blackdot repository
`~/.blackdot-backups/`	Backup storage
`~/.blackdot-metrics.jsonl`	Health check metrics
`~/workspace/.notes.md`	Quick notes
`vault/.vault-session`	Cached vault session
`templates/_variables.local.sh`	Local template overrides (repo-specific)
`~/.config/blackdot/template-variables.sh`	Template variables (XDG, vault-portable)
`generated/`	Rendered templates
`~/.config/blackdot/config.json`	All configuration and state (JSON format)
`~/.config/blackdot/vault-items.json`	Vault items schema
`~/.cache/blackdot/vault-state.json`	Drift detection cache (file checksums from last vault pull)

State Management

The blackdot setup wizard uses persistent state in JSON format. See State Management for full documentation.

Configuration File

`~/.config/blackdot/config.json`

All state and configuration in a single JSON file:

{
  "version": 3,
  "vault": {
    "backend": "bitwarden",
    "auto_sync": false,
    "auto_backup": true
  },
  "setup": {
    "completed": ["symlinks", "packages", "vault", "secrets"],
    "current_tier": "enhanced"
  },
  "paths": {
    "blackdot_dir": "~/workspace/blackdot",
    "config_dir": "~/.config/blackdot"
  }
}

Key Sections:

setup.completed[] - Array of completed setup phases
vault.backend - Preferred vault backend (bitwarden, 1password, pass)
paths.blackdot_dir - Custom blackdot installation directory

Completed Phases:

symlinks - Shell configuration symlinks created
packages - Homebrew packages installed
vault - Vault backend selected and authenticated
secrets - Secrets restored from vault
claude - Claude Code integration configured
template - Machine-specific templates configured

State Commands

blackdot setup --status    # Show current setup state
blackdot setup --reset     # Reset state and re-run setup

State Inference

If state files don't exist, blackdot setup infers state from the filesystem:

Symlinks: Checks if ~/.zshrc points to blackdot
Packages: Checks if Homebrew is installed
Vault: Checks for vault CLI and credentials
Secrets: Checks for ~/.ssh/config, ~/.gitconfig
Claude: Checks if Claude CLI is installed

Claude Code Commands

Commands for working with Claude Code across different backends.

`claude`

Run Claude Code with automatic path normalization for portable sessions.

claude [ARGS...]

Behavior:

If in ~/workspace/* and /workspace exists, automatically redirects to /workspace/*
Shows educational message explaining session portability
Passes all arguments to claude

Why: Claude Code stores sessions by working directory path. The /workspace symlink ensures identical paths across macOS, Linux, WSL, etc.

`claude-bedrock` / `cb`

Run Claude Code via AWS Bedrock.

claude-bedrock [ARGS...]
cb [ARGS...]              # Alias

Requirements:

CLAUDE_BEDROCK_PROFILE set in ~/.claude.local
Valid AWS SSO session (auto-prompts if expired)

Environment set:

AWS_PROFILE - Your Bedrock profile
AWS_REGION - Bedrock region
CLAUDE_CODE_USE_BEDROCK=1
ANTHROPIC_MODEL - Bedrock model ID

`claude-max` / `cm`

Run Claude Code via Anthropic Max subscription.

claude-max [ARGS...]
cm [ARGS...]              # Alias

Clears all Bedrock-related environment variables to use your Max subscription.

`claude-run`

Unified command to run Claude with a specific backend.

claude-run {bedrock|max} [ARGS...]

Examples:

claude-run bedrock         # Use AWS Bedrock
claude-run max             # Use Anthropic Max

`claude-status`

Show current Claude Code configuration.

claude-status

Output includes:

Session portability status
Max output tokens setting
Bedrock configuration (profile, region, model)
SSO authentication status

Claude Configuration

Configuration file: ~/.claude.local

# AWS Bedrock settings
export CLAUDE_BEDROCK_PROFILE="your-sso-profile"
export CLAUDE_BEDROCK_REGION="us-west-2"
export CLAUDE_BEDROCK_MODEL="us.anthropic.claude-sonnet-4-5-20250929-v1:0"
export CLAUDE_BEDROCK_FAST_MODEL="us.anthropic.claude-3-5-haiku-20241022-v1:0"

AWS Commands

AWS profile management, SSO authentication, and role assumption helpers.

Overview

Command	Description
`awsprofiles`	List all profiles (* = active)
`awsswitch`	Fuzzy-select profile (fzf) + auto-login
`awsset <profile>`	Set AWS_PROFILE for this shell
`awsunset`	Clear AWS_PROFILE
`awslogin [profile]`	SSO login (defaults to current profile)
`awswho`	Show current identity (account/user/ARN)
`awsassume <arn>`	Assume role for cross-account access
`awsclear`	Clear temporary assumed-role credentials
`awstools`	Show all AWS commands with banner

`awsprofiles`

List all configured AWS profiles.

awsprofiles

Shows * next to the currently active profile.

`awsswitch`

Interactive profile selector using fzf.

awsswitch

Presents fuzzy-searchable list of profiles
Sets AWS_PROFILE on selection
Auto-triggers SSO login if session expired
Shows identity after switch

Requires: fzf

`awsset` / `awsunset`

Set or clear AWS profile for current shell.

awsset <profile>   # Set AWS_PROFILE
awsunset           # Clear AWS_PROFILE

`awslogin`

SSO login helper.

awslogin [profile]

If no profile specified, uses $AWS_PROFILE or defaults to dev-profile.

`awswho`

Show current AWS identity.

awswho

Displays account, user, and ARN via aws sts get-caller-identity.

`awsassume` / `awsclear`

Assume a role for cross-account access.

awsassume <role-arn> [session-name]
awsclear    # Clear temporary credentials

Sets AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN.

`awstools`

Show all AWS commands with decorative banner.

awstools

Git Shortcuts

Git aliases and cross-platform clipboard utilities.

Git Aliases

Alias	Command	Description
`gst`	`git status`	Status
`gss`	`git status -sb`	Short status
`ga`	`git add`	Add files
`gaa`	`git add --all`	Add all files
`gb`	`git branch`	List branches
`gba`	`git branch -a`	List all branches
`gco`	`git checkout`	Checkout
`gcb`	`git checkout -b`	Create and checkout branch
`gd`	`git diff`	Diff
`gds`	`git diff --staged`	Diff staged changes
`gpl`	`git pull`	Pull
`gp`	`git push`	Push
`gpf`	`git push --force-with-lease`	Force push (safe)
`gcm`	`git commit -m`	Commit with message
`gca`	`git commit --amend`	Amend commit
`gcl`	`git clone`	Clone
`gl1`	`git log --oneline -n 15`	Short log (15 commits)
`glg`	`git log --oneline --graph --all`	Graph log

Clipboard Functions

Cross-platform clipboard utilities (macOS, Linux, WSL).

echo "text" | copy    # Copy to clipboard
paste                  # Paste from clipboard

Aliases:

cb - copy
cbp - paste

Supported backends:

macOS: pbcopy/pbpaste
Wayland: wl-copy/wl-paste
X11: xclip or xsel
WSL: clip.exe/PowerShell

Navigation Aliases

Quick navigation to common directories.

Alias	Destination
`cws`	`$WORKSPACE` (~/workspace)
`ccode`	`$WORKSPACE/code`
`cwhite`	`$WORKSPACE/whitepapers`
`cpat`	`$WORKSPACE/patent-pool`

Utility Functions

`j` - Project Jumper

Jump to any git project by fuzzy search.

j [BASE_DIR]

Searches for .git directories under /workspace (or specified base)
Uses fzf for fuzzy selection
Preview shows directory contents

Requires: fzf, optionally fd for faster search

`note` / `notes` - Quick Notes

Capture timestamped notes instantly.

note "Your note text"     # Add a note
notes                      # View recent notes (last 20)
notes all                  # View all notes
notes edit                 # Open notes file in $EDITOR
notes search <term>        # Search notes

Notes stored in ~/workspace/.notes.md.

Uh oh!

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

CLI Reference

Quick Reference

The blackdot Command

Command Overview

Status & Health Commands

blackdot status

blackdot doctor

Feature Management

blackdot features

Hook Commands

blackdot hook

Hook Points

Creating Hooks

Configuration Commands

blackdot config

blackdot drift

blackdot sync

blackdot diff

Backup & Restore

blackdot backup

blackdot migrate

Vault Commands

blackdot vault

vault create

vault delete

Supported Backends

Switching Backends

Backend Setup

Location Management

Configuration File

Example Managed Items

blackdot vault pull

blackdot vault push

blackdot vault sync

blackdot vault list

blackdot vault check

blackdot vault validate

Template Commands

blackdot template

blackdot template init

blackdot template render

blackdot template vars

blackdot template link

blackdot template diff

blackdot template list

blackdot template vault

Encryption Commands

blackdot encrypt

blackdot encrypt init

blackdot encrypt <file>

blackdot encrypt decrypt <file>

blackdot encrypt edit

blackdot encrypt list

blackdot encrypt status

blackdot encrypt push-key

Encryption + Hooks Integration

When to Use Encryption vs Vault

Maintenance Commands

blackdot lint

blackdot packages

blackdot upgrade

blackdot setup

blackdot uninstall

blackdot metrics

macOS Commands

blackdot macos

blackdot macos apply

blackdot macos preview

blackdot macos discover

Devcontainer Commands

blackdot devcontainer

blackdot devcontainer init

blackdot devcontainer images

The `blackdot` Command

`blackdot status`

`blackdot doctor`

`blackdot features`

`blackdot hook`

`blackdot config`

`blackdot drift`

`blackdot sync`

`blackdot diff`

`blackdot backup`

`blackdot migrate`

`blackdot vault`

`blackdot vault pull`

`blackdot vault push`

`blackdot vault sync`

`blackdot vault list`

`blackdot vault check`

`blackdot vault validate`

`blackdot template`

`blackdot template init`

`blackdot template render`

`blackdot template vars`

`blackdot template link`

`blackdot template diff`

`blackdot template list`

`blackdot template vault`

`blackdot encrypt`

`blackdot encrypt init`

`blackdot encrypt <file>`

`blackdot encrypt decrypt <file>`

`blackdot encrypt edit`

`blackdot encrypt list`

`blackdot encrypt status`

`blackdot encrypt push-key`

`blackdot lint`

`blackdot packages`

`blackdot upgrade`

`blackdot setup`

`blackdot uninstall`

`blackdot metrics`

`blackdot macos`

`blackdot macos apply`

`blackdot macos preview`

`blackdot macos discover`

`blackdot devcontainer`

`blackdot devcontainer init`

`blackdot devcontainer images`

`blackdot tools`

`blackdot cd`

`blackdot edit`

`install.sh`

`status`

`j`

`note` / `notes`

`blackdot upgrade`

`~/.config/blackdot/config.json`

`claude`

`claude-bedrock` / `cb`

`claude-max` / `cm`

`claude-run`

`claude-status`

`awsprofiles`

`awsswitch`

`awsset` / `awsunset`

`awslogin`

`awswho`

`awsassume` / `awsclear`

`awstools`

`j` - Project Jumper

`note` / `notes` - Quick Notes