Getting Started

This guide describes how to evaluate the current tilde proof of concept from source. tilde is not published to npm yet, so npm install -g @jwill824/tilde, npx @jwill824/tilde, and the hosted curl installer are not available as end-user installation paths.

Prerequisites

• macOS (Apple Silicon recommended; Intel supported)
• Node.js 20+
• Git
• An internet connection (tilde downloads tools on first run)

Run from source

Clone the repository, install dependencies, build the CLI, and inspect the available commands:

git clone https://github.com/jwill824/tilde.git
cd tilde
npm install
npm run build
node dist/bin/tilde.js --help

Running from source is intended for project evaluation and development while the npm package and hosted installer are prepared.

Navigating the wizard

Use these keyboard shortcuts at any time:

Key	Action
← / b	Go back to the previous step (values restored)
s	Skip the current step (optional steps only)
q	Quit the wizard

On the first step, pressing b shows a reminder that there is no previous step. Optional steps — Editor Configuration, Browser Selection, and AI Coding Tools — are labelled with (opt) in the sidebar and can be skipped.

The setup wizard

tilde’s interactive wizard walks you through 13 steps. Steps 0–1 run automatically (no input required); steps 2–12 are interactive.

0. Config Detection (automated)

tilde scans three locations for an existing tilde.config.json:

1. The current working directory
2. The git repository root of the current directory (if inside a git repo)
3. ~/.tilde/tilde.config.json (the canonical location written after each wizard run)

If no config is found, the wizard proceeds to full setup. If a config is found, tilde shows a summary and asks what you’d like to do (see Re-running tilde below).

1. Environment Capture (automated)

tilde scans your machine for installed tools, shell rc files, git config, Homebrew packages, and programming languages already present. This information pre-fills later steps.

2. Shell

tilde asks which shell you use:

• zsh (default on macOS)
• bash
• fish

3. Package Manager

Choose your preferred macOS package manager:

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

4. Version Manager

Select how you want to manage programming language versions:

• vfox — universal, shell-agnostic version manager (recommended)
• nvm — Node.js version manager
• fnm — fast Node.js version manager
• pyenv — Python version manager
• rbenv — Ruby version manager
• python-venv — Python virtual environment manager
• sdkman — JVM/JDK version manager

5. Workspace & Contexts

All workspace, identity, and language configuration is collected in one step:

1. Workspace root — the parent directory for all project folders (e.g., ~/Developer)
2. Named contexts — one entry per identity (personal, work, etc.), each with:
   • Context label and workspace path
   • Git name and email
   • GitHub authentication method (gh-cli, https, or ssh)
   • GitHub username (optional)
   • Dotfiles path (optional)
   • Language version bindings (optional — see below)
3. Language version bindings — per context, select languages and specify versions:
   • Supported: Node.js, Python, Ruby, Go, Java, Rust
   • For each language, choose a version manager and version (or enter manually)

6. Tools & Applications

Select CLI tools and applications 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

7. Editor Configuration (optional)

Choose a primary code editor to install via Homebrew Cask:

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

8. Secrets Backend

Configure a secrets backend to sync credentials and tokens:

• 1Password CLI (recommended for macOS)
• macOS Keychain
• Environment variables only

9. Browser Selection (optional)

Choose a browser to install via Homebrew Cask:

• Google Chrome
• Firefox
• Arc
• Brave
• Safari (pre-installed)

10. AI Coding Tools (optional)

Choose AI coding tools to install via Homebrew:

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

11. Config Export

Review your complete configuration before it is written to disk. tilde writes ~/.tilde/tilde.config.json (or a custom path) at this step.

12. Apply & Finish

tilde runs all installation and configuration steps based on your saved config. Progress is shown in real time.

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 (canonical copy) and optionally to your dotfiles repo if you specified one during setup.

Re-running tilde

After completing the initial setup from source, run node dist/bin/tilde.js from the project checkout to manage your configuration. If a config file is found, tilde shows the Configuration Summary and a menu with four options:

Option	What it does
Apply this configuration	Re-runs all installs and dotfile writes using the saved config
Edit configuration	Re-opens the full wizard with all steps pre-populated from your saved config
Start over (run wizard)	Clears state and runs a fresh wizard from scratch
Cancel	Exits without making any changes

The config file path is shown at the bottom of the summary so you always know which file is being used.

Updating your config

The easiest way to update your configuration is to run node dist/bin/tilde.js from the project checkout and select Edit configuration from the menu. This opens the full wizard pre-populated with your current settings — navigate to the step you want to change and save.

For targeted one-step updates, use node dist/bin/tilde.js update <resource>:

# Change your shell
node dist/bin/tilde.js update shell

# Add or remove browsers
node dist/bin/tilde.js update browser

# Add AI coding tools
node dist/bin/tilde.js update ai-tools

# Edit workspace contexts or language bindings
node dist/bin/tilde.js update contexts

Valid resources

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

Specifying a config path

node dist/bin/tilde.js 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 the source command again.

Permission errors during dependency install

If you see EACCES errors while installing dependencies, your npm cache or project directory may have files owned by another user. Check ownership before rerunning npm install.

Global npm installation guidance will be added after tilde is published.

Wizard exits unexpectedly

If the wizard exits without completing:

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