Getting Started

This guide walks you through your first tilde run after installation.

Prerequisites

• macOS (Apple Silicon recommended; Intel supported)
• Node.js 20+ — installed automatically if you used the curl installer
• An internet connection (tilde downloads tools on first run)

Launch tilde

If you installed via curl, tilde launches automatically at the end of the install script. To run it again at any time:

tilde

Navigating the wizard

At any step (except the first), use ← Back to return to the previous step — your values are restored. Optional steps (Editor, Applications, Browser, AI Tools) show a Skip option.

The setup wizard

tilde’s interactive wizard walks you through each configuration category in order. You can skip any category and revisit it later by re-running tilde.

1. Shell

tilde asks which shell you use:

• zsh (default on macOS)
• bash
• fish

2. Package manager

Choose your preferred macOS package manager:

• Homebrew (recommended) — tilde uses Homebrew to install all command-line tools.

3. Version manager

Select how you want to manage programming language versions:

• vfox — universal, shell-agnostic version manager (recommended)
• nvm — Node.js version manager
• pyenv — Python version manager
• sdkman — JVM/JDK version manager

4. Languages

Select which programming languages to configure. For each language, tilde asks for your preferred version (or uses the latest stable).

Supported: Node.js, Python, Ruby, Go, Java, Rust

5. Workspace

Configure your local directory structure — tilde creates a ~/dev/ workspace (or your preferred path) with per-account project folders.

6. Git identity

Set your global git name, email, and default branch name. If you have multiple GitHub accounts (personal + work), tilde configures per-directory git identities.

7. GitHub accounts

Connect one or more GitHub accounts. tilde configures SSH keys and git credential helpers for each account.

8. Tools

Select additional CLI tools to install via Homebrew:

• Docker Desktop
• VS Code (via Homebrew Cask)
• Terraform, kubectl, helm (cloud/infra tools)
• Any custom tools you add to tilde.config.json

9. Secrets

Configure a secrets backend to sync credentials and tokens:

• 1Password CLI (recommended for macOS)
• Bitwarden CLI
• Environment file (plain .env — not recommended for shared machines)

10. Editor (optional)

Choose a primary code editor to install via Homebrew Cask:

• VS Code
• Cursor (AI Editor)
• Neovim
• JetBrains Toolbox
• Zed

11. Applications (optional)

Select additional CLI tools and applications to install.

12. Review & Export

Review your complete configuration before it is written to disk. tilde writes ~/.tilde/tilde.config.json at this step.

13. Browser (optional)

Choose a browser to install via Homebrew Cask. This step occurs after config export so it can be skipped without affecting your saved config:

• Google Chrome
• Firefox
• Arc
• Brave

14. AI Tools (optional)

Choose AI coding tools to install via Homebrew:

• Claude Code (CLI)
• Claude Desktop (desktop app)
• Cursor (AI Editor)
• Windsurf
• GitHub Copilot CLI

Expected output

A successful first run looks like this:

tilde 🌿 — macOS Developer Environment Setup

  ✓  Shell: zsh
  ✓  Package manager: Homebrew
  ✓  Version manager: vfox
  ✓  Languages: Node.js 20, Python 3.12
  ✓  Workspace: ~/dev/
  ✓  Git identity configured
  ✓  GitHub: jwill824 (SSH key added)
  ✓  Tools: docker, code, terraform
  ✓  Secrets: 1Password CLI linked
  ✓  Editor: VS Code
  ✓  Browser: Arc
  ✓  AI tools: Claude Code, GitHub Copilot CLI

  Setup complete. Your environment is ready. 🎉

Your configuration is saved to ~/.tilde/tilde.config.json.

Updating your config

After initial setup, use tilde update <resource> to change one part of your config without re-running the full wizard.

Examples

# Change your shell
tilde update shell

# Add or remove browsers
tilde update browser

# Add AI coding tools
tilde update ai-tools

# Edit workspace contexts or language bindings
tilde update contexts

Valid resources

shell, editor, applications, browser, ai-tools, contexts, languages

Specifying a config path

tilde update shell --config ~/dotfiles/tilde.config.json

Troubleshooting

Node.js not found

If tilde reports node: command not found, make sure your shell profile sources the Node.js path. Run:

source ~/.zshrc   # or ~/.bashrc / ~/.config/fish/config.fish

Then try tilde again. If you used the curl installer, it adds Node.js to your PATH automatically.

Permission errors on npm global install

If you see EACCES errors, your npm global prefix may be owned by root. Fix with:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"

Add the export PATH line to your shell profile (~/.zshrc or ~/.bashrc).

Wizard exits unexpectedly

If the wizard exits without completing:

1. Check the error message — it will indicate which step failed.
2. Run tilde --debug for verbose output.
3. Re-run tilde — it is idempotent and will resume from where it can.
4. Open an issue with the debug output.