tfv 6.0.0 → 6.1.0

package/.github/workflows/publish.yml

@@ -10,7 +10,23 @@ permissions:
   id-token: write
 
 jobs:
+  verify-branch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag is on main branch
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor ${{ github.sha }} origin/main; then
+            echo "Error: tags must only be pushed on commits that exist on the main branch."
+            exit 1
+          fi
+
   test:
+    needs: verify-branch
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

package/README.md

@@ -1,6 +1,6 @@
-# tfv — Terraform & OpenTofu Version Manager
+# tfv — Terraform & OpenTofu Version Manager for macOS, Linux & Windows
 
-```
+```text
          _        ________        __
        _| |__   / _____|\ \      / /
       |_  ___\ | |___    \ \    / /
@@ -30,7 +30,7 @@ npm install -g tfv
 
 ## How it works
 
-```
+```text
 npm install -g tfv
        │
        ▼
@@ -63,7 +63,7 @@ Both `terraform` and `tfv` commands always use the **exact same binary**.
 
 ## Store layout
 
-```
+```text
 ~/.tfv/
   bin/
     terraform          ← active terraform binary (no sudo, no symlinks)
@@ -137,6 +137,7 @@ Reads version from (in priority order):
 Wraps `cd` so that entering a directory automatically switches the terraform version — but **only if the directory looks like a terraform project**. Non-terraform folders have zero overhead (one filesystem check, no subprocess).
 
 A directory is considered a terraform project if it contains:
+
 - a `.terraform-version` file, **or**
 - any `*.tf` files
 
@@ -151,20 +152,22 @@ Setup (one-time, add to your shell config):
 
 ```sh
 # Bash
-echo 'eval "$(tfv shell-init bash)"' >> ~/.bashrc
+printf '\neval "$(tfv shell-init bash)"\n' >> ~/.bashrc
 
 # Zsh
-echo 'eval "$(tfv shell-init zsh)"' >> ~/.zshrc
+printf '\neval "$(tfv shell-init zsh)"\n' >> ~/.zshrc
 
 # Fish
-echo 'tfv shell-init fish | source' >> ~/.config/fish/config.fish
+printf '\ntfv shell-init fish | source\n' >> ~/.config/fish/config.fish
 
 # PowerShell
-echo 'Invoke-Expression (tfv shell-init powershell | Out-String)' >> $PROFILE
+Add-Content $PROFILE "`nInvoke-Expression (tfv shell-init powershell | Out-String)"
 ```
 
 After setup, entering a terraform project switches the version automatically — no manual `tfv as` needed.
 
+`shell-init` also installs **tab completions** for all `tfv` commands and installed versions. After running the setup command above, `tfv <tab>` will complete commands, `tfv use <tab>` will complete installed versions, and `tfv --provider <tab>` will complete provider names.
+
 ---
 
 ### List versions
@@ -188,7 +191,8 @@ tfv current --provider tofu
 ```
 
 Example output:
-```
+
+```text
 Active terraform version: 1.9.0
 Binary: /Users/you/.tfv/bin/terraform
 Reported: Terraform v1.9.0
@@ -234,6 +238,75 @@ Warns if you're removing the currently active version.
 
 ---
 
+### Prune
+
+Remove all non-active versions at once to free disk space.
+
+```sh
+tfv prune                            # remove everything except the active version
+tfv prune --keep 2                   # keep the 2 most recent + the active version
+tfv prune --provider tofu
+tfv prune --yes                      # skip confirmation prompt
+```
+
+The active version is always kept regardless of `--keep`.
+
+---
+
+### Exec
+
+Run a single command with a specific installed version **without** changing the active version. Useful for cross-version testing and CI.
+
+```sh
+tfv exec 1.9.0 -- version
+tfv exec 1.8.0 -- plan -var="env=prod"
+tfv exec 1.7.3 --provider tofu -- validate
+```
+
+Pass all terraform/tofu flags after `--`.
+
+---
+
+### Doctor
+
+Run a full health check: store directories, active binaries, PATH order, PATH conflicts, and shell config.
+
+```sh
+tfv doctor
+```
+
+Example output:
+
+```text
+tfv doctor
+
+Store
+  ✔  ~/.tfv/store/terraform/ exists
+  ✔  ~/.tfv/store/opentofu/ exists
+
+Active versions
+  ✔  terraform: active version is 1.9.0
+  ✔  terraform: binary exists
+  ✔  terraform: executes  (Terraform v1.9.0)
+  –  tofu: not set up (no versions installed)
+
+PATH
+  ✔  ~/.tfv/bin is in PATH
+  ✔  ~/.tfv/bin precedes system dirs in PATH
+  ✔  'terraform' resolves to tfv-managed binary
+  ✔  PATH block found in shell config (~/.zshrc)
+
+Cache
+  ✔  terraform version cache exists
+  –  opentofu version cache not yet created
+
+All checks passed. tfv is healthy.
+```
+
+Exits with code 1 if any issue is found.
+
+---
+
 ### Terraform commands (via tfv)
 
 All commands use the tfv-managed binary and accept extra terraform flags after `--`:

package/lib/commands/doctor.js

@@ -0,0 +1,20 @@
+'use strict'
+
+const { doctor } = require('../modules/doctor');
+
+exports.command = 'doctor'
+exports.desc = 'Run diagnostics: PATH, binaries, store, shell config'
+exports.builder = (yargs) => {
+  return yargs
+    .epilog([
+      'Checks PATH order, active binaries, store directories,',
+      'shell config, and PATH conflicts.',
+      '',
+      'Example:',
+      '  tfv doctor',
+    ].join('\n'))
+}
+
+exports.handler = async () => {
+  await doctor();
+}

package/lib/commands/exec.js

@@ -0,0 +1,33 @@
+'use strict'
+
+const { exec } = require('../modules/exec');
+
+exports.command = 'exec <ver>'
+exports.desc = 'Run a terraform/tofu command with a specific version without switching the active version'
+exports.builder = (yargs) => {
+  return yargs
+    .positional('ver', {
+      describe: 'Installed version to use for this run',
+      type: 'string',
+    })
+    .option('provider', {
+      alias: 'p',
+      describe: 'Provider: terraform (default) or tofu/opentofu',
+      type: 'string',
+      default: 'terraform',
+    })
+    .epilog([
+      'Pass terraform/tofu args after --',
+      '',
+      'Examples:',
+      '  tfv exec 1.9.0 -- version',
+      '  tfv exec 1.8.0 -- plan -var="env=prod"',
+      '  tfv exec 1.7.3 --provider tofu -- validate',
+    ].join('\n'))
+}
+
+exports.handler = async (argv) => {
+  const { ver, provider, _ } = argv;
+  const extraArgs = _.slice(1);
+  await exec(ver, extraArgs, provider);
+}

package/lib/commands/prune.js

@@ -0,0 +1,41 @@
+'use strict'
+
+const { prune } = require('../modules/prune');
+
+exports.command = 'prune'
+exports.desc = 'Remove all non-active installed versions to free disk space'
+exports.builder = (yargs) => {
+  return yargs
+    .option('keep', {
+      alias: 'k',
+      describe: 'Keep the N most recent versions in addition to the active one',
+      type: 'number',
+      default: 0,
+    })
+    .option('provider', {
+      alias: 'p',
+      describe: 'Provider: terraform (default) or tofu/opentofu',
+      type: 'string',
+      default: 'terraform',
+    })
+    .option('yes', {
+      alias: 'y',
+      describe: 'Skip confirmation prompt',
+      type: 'boolean',
+      default: false,
+    })
+    .epilog([
+      'Always keeps the currently active version.',
+      '',
+      'Examples:',
+      '  tfv prune                   # remove all but active',
+      '  tfv prune --keep 2          # remove all but active + 2 most recent',
+      '  tfv prune --provider tofu',
+      '  tfv prune --yes             # skip confirmation',
+    ].join('\n'))
+}
+
+exports.handler = async (argv) => {
+  const { provider, keep, yes } = argv;
+  await prune(provider, keep, yes);
+}

package/lib/modules/doctor.js

@@ -0,0 +1,160 @@
+const { existsSync, readFileSync, readdirSync } = require('fs');
+const { join } = require('path');
+const { spawnSync } = require('child_process');
+const { platform, homedir } = require('os');
+const { getPaths, getBinTarget, getProviderStore, getCliName, normalizeProvider, checkPathConflict } = require('../utils/paths');
+const { P_END, P_OK, P_ERROR, P_WARN, P_INFO } = require('../utils/colors');
+
+const SHELL_CONFIGS = [
+  join(homedir(), '.zshrc'),
+  join(homedir(), '.bashrc'),
+  join(homedir(), '.bash_profile'),
+  join(homedir(), '.profile'),
+];
+const PATH_MARKER = '# tfv - terraform version manager';
+
+const ok   = (label, detail) => { console.log(`  ${P_OK}✔${P_END}  ${label}`); if (detail) console.log(`     ${P_INFO}${detail}${P_END}`); };
+const fail = (label, hint)   => { console.log(`  ${P_ERROR}✘${P_END}  ${label}`); if (hint) console.log(`     ${P_WARN}${hint}${P_END}`); };
+const info = (label, detail) => { console.log(`  ${P_INFO}–${P_END}  ${label}`); if (detail) console.log(`     ${P_INFO}${detail}${P_END}`); };
+
+exports.doctor = async () => {
+  const paths = getPaths();
+  const isWin = platform() === 'win32';
+  let issues = 0;
+
+  console.log(`\n${P_INFO}tfv doctor${P_END}\n`);
+
+  // ── Store ──────────────────────────────────────────────────────────────────
+  console.log(`${P_OK}Store${P_END}`);
+  for (const p of ['terraform', 'opentofu']) {
+    const store = getProviderStore(p);
+    if (existsSync(store)) {
+      ok(`~/.tfv/store/${p}/ exists`);
+    } else {
+      fail(`~/.tfv/store/${p}/ missing`, 'Run: tfv install latest' + (p === 'opentofu' ? ' --provider tofu' : ''));
+      issues++;
+    }
+  }
+
+  // ── Active versions & binaries ─────────────────────────────────────────────
+  console.log(`\n${P_OK}Active versions${P_END}`);
+  let activeData = { terraform: null, opentofu: null };
+  if (existsSync(paths.active)) {
+    try { activeData = JSON.parse(readFileSync(paths.active, 'utf-8')); } catch {}
+  }
+
+  for (const p of ['terraform', 'opentofu']) {
+    const cli = getCliName(p);
+    const binary = getBinTarget(p);
+    const active = activeData[p];
+
+    const store = getProviderStore(p);
+    const hasInstalled = existsSync(store) &&
+      readdirSync(store).filter(f => f !== 'arch.json').length > 0;
+
+    if (!active) {
+      if (hasInstalled) {
+        fail(`${cli}: no active version set`, `Run: tfv use <version>${p === 'opentofu' ? ' --provider tofu' : ''}`);
+        issues++;
+      } else {
+        info(`${cli}: not set up (no versions installed)`);
+      }
+      continue;
+    }
+
+    ok(`${cli}: active version is ${active}`);
+
+    if (!existsSync(binary)) {
+      fail(`${cli}: binary missing at ${binary}`, `Run: tfv use ${active}${p === 'opentofu' ? ' --provider tofu' : ''}`);
+      issues++;
+      continue;
+    }
+
+    ok(`${cli}: binary exists`);
+
+    const result = spawnSync(binary, ['version'], { stdio: 'pipe', encoding: 'utf-8' });
+    if (result.status === 0 && result.stdout) {
+      ok(`${cli}: executes  (${result.stdout.split('\n')[0].trim()})`);
+    } else {
+      fail(`${cli}: binary failed to execute`, result.stderr ? result.stderr.trim() : 'Unknown error');
+      issues++;
+    }
+  }
+
+  // ── PATH ──────────────────────────────────────────────────────────────────
+  console.log(`\n${P_OK}PATH${P_END}`);
+
+  if (isWin) {
+    info('PATH check skipped on Windows (managed via User PATH registry key)');
+  } else {
+    const pathEntries = (process.env.PATH || '').split(':');
+    const tfvBin = paths.bin;
+
+    if (pathEntries.includes(tfvBin)) {
+      ok('~/.tfv/bin is in PATH');
+
+      const tfvIdx = pathEntries.indexOf(tfvBin);
+      const systemDirs = ['/usr/bin', '/usr/local/bin', '/opt/homebrew/bin'];
+      const systemIdxs = systemDirs
+        .map(d => pathEntries.indexOf(d))
+        .filter(i => i >= 0);
+      const firstSystem = systemIdxs.length ? Math.min(...systemIdxs) : Infinity;
+
+      if (firstSystem < Infinity) {
+        if (tfvIdx < firstSystem) {
+          ok('~/.tfv/bin precedes system dirs in PATH');
+        } else {
+          fail('~/.tfv/bin comes AFTER system dirs in PATH', 'Run: tfv upgrade  to re-anchor PATH');
+          issues++;
+        }
+      }
+    } else {
+      fail('~/.tfv/bin is not in PATH', 'Run: tfv upgrade  to re-anchor PATH');
+      issues++;
+    }
+
+    for (const p of ['terraform', 'opentofu']) {
+      const active = activeData[p];
+      if (!active) continue;
+      const cli = getCliName(p);
+      const conflict = checkPathConflict(p);
+      if (conflict.ok) {
+        ok(`'${cli}' resolves to tfv-managed binary`);
+      } else {
+        fail(`'${cli}' resolves to wrong binary`, `Got: ${conflict.resolved}  Expected: ${conflict.expected}`);
+        issues++;
+      }
+    }
+
+    const configsWithMarker = SHELL_CONFIGS.filter(f => {
+      if (!existsSync(f)) return false;
+      try { return readFileSync(f, 'utf-8').includes(PATH_MARKER); } catch { return false; }
+    });
+    if (configsWithMarker.length > 0) {
+      ok(`PATH block found in shell config`, configsWithMarker.map(f => f.replace(homedir(), '~')).join(', '));
+    } else {
+      fail('PATH block not found in any shell config', `Add: export PATH="$HOME/.tfv/bin:$PATH"  to ~/.zshrc or ~/.bashrc`);
+      issues++;
+    }
+  }
+
+  // ── Cache ─────────────────────────────────────────────────────────────────
+  console.log(`\n${P_OK}Cache${P_END}`);
+  for (const p of ['terraform', 'opentofu']) {
+    const cacheFile = join(paths.cache, `${p}-versions.json`);
+    if (existsSync(cacheFile)) {
+      ok(`${p} version cache exists`);
+    } else {
+      info(`${p} version cache not yet created`, 'Will be built on next: tfv list --remote' + (p === 'opentofu' ? ' --provider tofu' : ''));
+    }
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────────────
+  console.log();
+  if (issues === 0) {
+    console.log(`${P_OK}All checks passed. tfv is healthy.${P_END}\n`);
+  } else {
+    console.log(`${P_ERROR}${issues} issue(s) found. See details above.${P_END}\n`);
+    process.exit(1);
+  }
+};

package/lib/modules/exec.js

@@ -0,0 +1,36 @@
+const { existsSync } = require('fs');
+const { spawn } = require('child_process');
+const { normalizeProvider, getCliName, getVersionFile } = require('../utils/paths');
+const { P_END, P_OK, P_ERROR, P_WARN, P_INFO } = require('../utils/colors');
+
+exports.exec = async (version, extraArgs = [], providerArg = 'terraform') => {
+  try {
+    const provider = normalizeProvider(providerArg);
+    const cli = getCliName(provider);
+    const binary = getVersionFile(provider, version);
+
+    if (!existsSync(binary)) {
+      console.log(`${P_ERROR}${provider} ${version} is not installed.${P_END}`);
+      console.log(`Run: ${P_OK}tfv install ${version}${provider === 'opentofu' ? ' --provider tofu' : ''}${P_END}`);
+      process.exit(1);
+    }
+
+    console.log(`${P_INFO}Using ${provider} ${version} (active version unchanged)${P_END}`);
+    if (extraArgs.length > 0) {
+      console.log(`${P_OK}Running: ${cli} ${extraArgs.join(' ')}${P_END}\n`);
+    }
+
+    const tf = spawn(binary, extraArgs, { stdio: 'inherit', cwd: process.cwd() });
+
+    tf.on('error', (err) => {
+      console.log(`${P_ERROR}Error executing ${cli} ${version}: ${err.message}${P_END}`);
+      process.exit(1);
+    });
+
+    tf.on('close', code => process.exit(code ?? 0));
+
+  } catch (err) {
+    console.log(`${P_ERROR}Error: ${err.message}${P_END}`);
+    process.exit(1);
+  }
+};

package/lib/modules/prune.js

@@ -0,0 +1,100 @@
+const { existsSync, readdirSync, unlinkSync, readFileSync, writeFileSync } = require('fs');
+const { join } = require('path');
+const readline = require('readline');
+const { normalizeProvider, getProviderStore, getVersionFile, getPaths } = require('../utils/paths');
+const { P_END, P_OK, P_ERROR, P_WARN, P_INFO } = require('../utils/colors');
+
+const sortVersionsDesc = (versions) => versions.sort((a, b) => {
+  const ap = a.split('.').map(n => parseInt(n, 10) || 0);
+  const bp = b.split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (bp[i] || 0) - (ap[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+});
+
+const confirm = (question) => new Promise(resolve => {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.question(question, ans => { rl.close(); resolve(ans.trim().toLowerCase()); });
+});
+
+exports.prune = async (providerArg = 'terraform', keep = 0, yes = false) => {
+  try {
+    const provider = normalizeProvider(providerArg);
+    const store = getProviderStore(provider);
+
+    if (!existsSync(store)) {
+      console.log(`${P_ERROR}No store found for ${provider}.${P_END}`);
+      process.exit(1);
+    }
+
+    const archFile = join(store, 'arch.json');
+    const archMap = existsSync(archFile) ? JSON.parse(readFileSync(archFile, 'utf-8')) : {};
+
+    const paths = getPaths();
+    let activeVersion = null;
+    if (existsSync(paths.active)) {
+      const active = JSON.parse(readFileSync(paths.active, 'utf-8'));
+      activeVersion = active[provider];
+    }
+
+    const installed = sortVersionsDesc(
+      readdirSync(store)
+        .filter(f => f !== 'arch.json')
+        .map(f => f.replace(/\.exe$/, ''))
+    );
+
+    if (installed.length === 0) {
+      console.log(`${P_WARN}No ${provider} versions installed.${P_END}`);
+      return;
+    }
+
+    // Build the keep set: active version is always kept; top N by semver if --keep N
+    const keepSet = new Set();
+    if (activeVersion) keepSet.add(activeVersion);
+    if (keep > 0) installed.slice(0, keep).forEach(v => keepSet.add(v));
+
+    const toRemove = installed.filter(v => !keepSet.has(v));
+
+    if (toRemove.length === 0) {
+      console.log(`${P_OK}Nothing to prune for ${provider}.${P_END}`);
+      if (activeVersion) console.log(`${P_INFO}Active version ${activeVersion} is kept.${P_END}`);
+      return;
+    }
+
+    console.log(`${P_INFO}Versions to remove (${provider}):${P_END}`);
+    toRemove.forEach(v => console.log(`  ${P_WARN}${v}${P_END}`));
+    console.log();
+    if (activeVersion) console.log(`${P_OK}Keeping (active): ${activeVersion}${P_END}`);
+    if (keep > 0) {
+      const kept = installed.filter(v => keepSet.has(v) && v !== activeVersion);
+      if (kept.length) console.log(`${P_OK}Keeping (--keep ${keep}): ${kept.join(', ')}${P_END}`);
+    }
+
+    if (!yes) {
+      const ans = await confirm(`\nRemove ${toRemove.length} version(s)? [y/N] `);
+      if (ans !== 'y' && ans !== 'yes') {
+        console.log(`${P_WARN}Aborted.${P_END}`);
+        return;
+      }
+    }
+
+    console.log();
+    toRemove.forEach(v => {
+      const file = getVersionFile(provider, v);
+      if (existsSync(file)) {
+        unlinkSync(file);
+        delete archMap[v];
+        console.log(`${P_OK}Removed ${provider} ${v}${P_END}`);
+      }
+    });
+
+    writeFileSync(archFile, JSON.stringify(archMap, null, 2));
+    console.log(`\n${P_OK}Done. Pruned ${toRemove.length} version(s).${P_END}`);
+
+  } catch (err) {
+    console.log(`${P_ERROR}Error: ${err.message}${P_END}`);
+    process.exit(1);
+  }
+};

package/lib/modules/shell-init.js

@@ -6,7 +6,7 @@ const BASH_ZSH_HOOK = `
 # tfv - terraform version manager shell integration
 # Add this to your shell config by running: eval "$(tfv shell-init <shell>)"
 _tfv_auto_switch() {
-  if [ -f ".terraform-version" ] || ls *.tf 2>/dev/null | head -1 >/dev/null 2>&1; then
+  if [ -f ".terraform-version" ] || find . -maxdepth 1 -name "*.tf" -print -quit 2>/dev/null | grep -q .; then
     tfv auto-switch --silent 2>/dev/null
   fi
 }
@@ -19,6 +19,47 @@ alias cd='_tfv_cd'
 
 # Run for the current directory on shell startup
 _tfv_auto_switch
+
+# ── Tab completions ────────────────────────────────────────────────────────
+_tfv_versions() {
+  ls "\$HOME/.tfv/store/\${1:-terraform}" 2>/dev/null | grep -v arch.json | sed 's/\\.exe\$//'
+}
+
+if [ -n "\${BASH_VERSION:-}" ]; then
+  _tfv_complete() {
+    local cur="\${COMP_WORDS[COMP_CWORD]}"
+    local prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    local cmds="install i use auto-switch as list ls current which pin upgrade remove rm exec prune doctor shell-init fmt init validate plan apply destroy"
+    case "\$prev" in
+      use|exec|remove|rm|pin|upgrade|install|i)
+        COMPREPLY=(\$(compgen -W "\$(_tfv_versions terraform) latest" -- "\$cur")) ;;
+      --provider|-p)
+        COMPREPLY=(\$(compgen -W "terraform tofu opentofu" -- "\$cur")) ;;
+      shell-init)
+        COMPREPLY=(\$(compgen -W "bash zsh fish powershell pwsh" -- "\$cur")) ;;
+      *)
+        COMPREPLY=(\$(compgen -W "\$cmds" -- "\$cur")) ;;
+    esac
+  }
+  complete -F _tfv_complete tfv
+elif [ -n "\${ZSH_VERSION:-}" ]; then
+  _tfv_complete() {
+    local cmds
+    cmds=(install i use auto-switch as list ls current which pin upgrade remove rm exec prune doctor shell-init fmt init validate plan apply destroy)
+    local prev="\${words[CURRENT-1]}"
+    case "\$prev" in
+      use|exec|remove|rm|pin|upgrade|install|i)
+        compadd -- \$(_tfv_versions terraform) latest ;;
+      --provider|-p)
+        compadd -- terraform tofu opentofu ;;
+      shell-init)
+        compadd -- bash zsh fish powershell pwsh ;;
+      *)
+        compadd -- "\$cmds[@]" ;;
+    esac
+  }
+  compdef _tfv_complete tfv 2>/dev/null
+fi
 `.trim();
 
 const FISH_HOOK = `
@@ -37,6 +78,39 @@ function cd
 end
 
 _tfv_auto_switch
+
+# ── Tab completions ────────────────────────────────────────────────────────
+function __tfv_installed_versions
+  set provider terraform
+  for i in (seq 1 (count $argv))
+    if test "$argv[$i]" = "--provider" -o "$argv[$i]" = "-p"
+      set next (math $i + 1)
+      if test $next -le (count $argv)
+        set p $argv[$next]
+        if test "$p" = "tofu" -o "$p" = "opentofu"
+          set provider opentofu
+        end
+      end
+    end
+  end
+  ls $HOME/.tfv/store/$provider 2>/dev/null | grep -v arch.json | string replace -r '\\.exe$' ''
+end
+
+set -l tfv_commands install i use auto-switch as list ls current which pin upgrade remove rm exec prune doctor shell-init fmt init validate plan apply destroy
+
+complete -c tfv -f
+complete -c tfv -n 'not __fish_seen_subcommand_from $tfv_commands' -a "$tfv_commands"
+
+for subcmd in use exec remove rm pin upgrade
+  complete -c tfv -n "__fish_seen_subcommand_from $subcmd" -a '(__tfv_installed_versions (commandline -opc))' -d 'Installed version'
+  complete -c tfv -n "__fish_seen_subcommand_from $subcmd" -a 'latest' -d 'Latest version'
+end
+
+complete -c tfv -n "__fish_seen_subcommand_from install i" -a '(__tfv_installed_versions (commandline -opc))' -d 'Installed version'
+complete -c tfv -n "__fish_seen_subcommand_from install i" -a 'latest' -d 'Latest version'
+
+complete -c tfv -l provider -s p -r -a 'terraform tofu opentofu' -d 'Provider'
+complete -c tfv -n "__fish_seen_subcommand_from shell-init" -a 'bash zsh fish powershell pwsh' -d 'Shell'
 `.trim();
 
 const POWERSHELL_HOOK = `
@@ -57,6 +131,42 @@ Set-Alias -Name cd -Value Set-LocationWithTfv -Scope Global -Force
 
 # Run for current directory on shell startup
 Set-LocationWithTfv -Path $PWD
+
+# ── Tab completions ────────────────────────────────────────────────────────
+Register-ArgumentCompleter -Native -CommandName tfv -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+
+  $commands = @('install','i','use','auto-switch','as','list','ls','current','which','pin','upgrade','remove','rm','exec','prune','doctor','shell-init','fmt','init','validate','plan','apply','destroy')
+  $elements = $commandAst.CommandElements
+  $prev = if ($elements.Count -ge 2) { $elements[$elements.Count - 2].ToString() } else { '' }
+
+  # Detect --provider / -p anywhere on the line
+  $provider = 'terraform'
+  for ($i = 1; $i -lt $elements.Count - 1; $i++) {
+    if ($elements[$i].ToString() -in '--provider','-p') {
+      $pval = $elements[$i+1].ToString()
+      if ($pval -in 'tofu','opentofu') { $provider = 'opentofu' }
+    }
+  }
+
+  $storeDir = Join-Path $env:USERPROFILE ".tfv\\store\\$provider"
+  $installed = if (Test-Path $storeDir) {
+    Get-ChildItem $storeDir -ErrorAction SilentlyContinue |
+      Where-Object { $_.Name -ne 'arch.json' } |
+      ForEach-Object { $_.Name -replace '\\.exe$','' }
+  } else { @() }
+
+  $completions = switch ($prev) {
+    { $_ -in 'use','exec','remove','rm','pin','upgrade','install','i' } { @($installed) + 'latest' }
+    { $_ -in '--provider','-p' }  { 'terraform','tofu','opentofu' }
+    'shell-init'                  { 'bash','zsh','fish','powershell','pwsh' }
+    default                       { $commands }
+  }
+
+  $completions | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}
 `.trim();
 
 const INSTALL_INSTRUCTIONS = {
@@ -105,9 +215,12 @@ exports.shellInit = (shell) => {
     process.stdout.write(BASH_ZSH_HOOK + '\n');
   }
 
-  // Print install instructions to stderr so they don't get eval'd
+  // Only print install instructions when stdout is a TTY (i.e. the user ran
+  // tfv shell-init directly). When called inside $() for eval, stdout is a
+  // pipe so isTTY is falsy — suppress the message to avoid it printing on
+  // every `source ~/.zshrc`.
   const key = s === 'pwsh' ? 'powershell' : s;
-  if (INSTALL_INSTRUCTIONS[key]) {
+  if (INSTALL_INSTRUCTIONS[key] && process.stdout.isTTY) {
     process.stderr.write(INSTALL_INSTRUCTIONS[key] + '\n');
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tfv",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "publishConfig": {
     "access": "public",
     "provenance": true