AutoVaultv0.2.1
Markdown
Troubleshooting · 6 min read

Something didn't import?
Re-run the wizard from a real terminal.

Most install-time confusion comes down to two things: the setup wizard was skipped because it ran without a TTY, or the wizard ran in augment mode when you wanted backup. Both have clean recoveries — no reinstall required.

setup wizardadoption modesno TTYsync-profilesdoctor

Frequently asked questions

Each entry links the symptom you're seeing to the recovery command and explains what each command actually changes on disk.

My existing ~/.claude/skills didn't import after install

"I installed AutoVault via Claude Code. My existing ~/.claude/skills didn't get imported. How do I force an import now?"

  1. Open a real terminal — not a shell tool inside another agent. Installers run there as subprocesses without a TTY, so the interactive wizard is silently skipped.
  2. Run autovault setup.
  3. When the wizard reports your native skills, choose the backup adoption mode. augment (the safe default) only refreshes profile links — it does not ingest your existing content. This is the single most common point of confusion.
  4. Reload your Claude Code session so the new skill list is picked up.
Why this is a footgun. augment is the safe default because it never touches your existing native skill directories. If you came expecting "import my existing skills," you'll see nothing change — and conclude AutoVault didn't work. The fix is to re-run autovault setup and pick backup.

"autovault setup requires an interactive terminal"

The wizard cannot run inside a subprocess without a TTY. Two options:

  • Open a real terminal (Terminal.app, iTerm, your OS shell) and re-run autovault setup.
  • For a non-interactive scan (CI, automation, dry-run), use autovault setup --json. That emits a DriftReport describing what would be adopted without prompting and without making any change.

Verified: autovault setup exits with code 2 and a NoTtyError when invoked without a TTY — see autovault/src/cli/ui/tty.ts:13.

What's the difference between augment, backup, and in-place?

These are the three adoption modes the wizard offers. They differ in what they do to your existing native skill directories on disk.

augment · safe default

Refreshes profile symlinks for skills already in the vault. Your existing native skill directories are not touched. Nothing under ~/.claude/skills moves.

Pick this when you want bundled AutoVault skills available alongside your native ones without importing the native ones.

backup · the import path

fs.renames each native skill directory to <root>.bak/<name>, admits the bytes into the vault through the validation gate, then replaces the original with a managed symlink. Refuses to overwrite an existing backup.

Pick this when you want to "import my existing skills." Originals stay on disk under .bak/ so you can roll back.

in-place · destructive

Admits the native bytes into the vault, then rm -rfs the native directory and replaces it with a managed symlink. No backup.

Only pick this when you're certain you want to delete the originals. There is no undo.

Source: autovault/src/cli/setup/apply.ts — backup at lines 45–57, in-place at lines 119–131, augment short-circuits collision handling at line 195+.

autovault sync-profiles --discover crashed with ENOENT scandir '.autovault/skills'

The vault directory was initialized but no skills have been installed yet — typically because both bundled bootstrap and the setup wizard were skipped at install time. Run autovault setup first. The wizard creates the expected directory tree and admits any bundled skills.

Upstream issue: sync should treat an empty vault as a no-op rather than crash. File a report at autoworks-ai/autovault if this persists after the next release.

autovault doctor reports a signature mismatch on one of my skills

Run autovault doctor --repair. The repair flow re-signs unsigned local skills only — it refuses tampered metadata and remote sources. Today the doctor logs mismatches but does not enforce; future versions may reject mismatched signatures at load time.

$ autovault doctor --repair

Source: autovault/src/cli/doctor.ts:157–226. Added in autovault commit 0c0d78a (PR #51).

A skill was admitted but doesn't show up in Claude Code

Reload your Claude Code session. The setup wizard runs sync-profiles as its final step, which reports restart_required: true when symlinks change — agents like Claude Code need a session reload to pick up the new skill list.

Confirm where the skill is resolved from:

$ autovault skill which <name>

That prints the resolved script path(s) — vault, bundled, or native — so you can verify the symlink actually exists.

Can I move an existing skill into the vault without using the setup wizard?

Yes. Use add-local directly:

$ autovault add-local <skill-dir> --source native:claude-code --sync-profiles

Sync refuses to overwrite an existing user-managed native directory, so move the native dir aside first if you want the managed symlink:

$ mv ~/.claude/skills/<name> ~/.claude/skills.bak/<name>
$ autovault add-local ~/.claude/skills.bak/<name> --source native:claude-code --sync-profiles

Troubleshooting matrix

If you know the symptom but not the cause, start here.

SymptomDiagnosticLikely causeFix
Installer finished but autovault is not on PATHwhich autovaultShell profile not sourced after install.Run . ~/.autovault/env or open a new shell.
Setup wizard skipped silently after installautovault setup --jsonInstaller ran without a TTY (e.g., inside another agent's shell tool).Run autovault setup from a real terminal.
Adoption ran but the native directory still shows the old contentls -la ~/.claude/skills/<name>augment mode was picked — native dirs were intentionally left untouched.Re-run autovault setup and pick backup.
MCP server fails to start in Claude CodeCheck ~/.claude/mcp.json (or ~/.config/claude/mcp.json)Wrong path to dist/index.js or missing binding.Fix the path. See INSTALL.md in the autovault repo for the host config snippets.
Signature mismatch reported by doctorautovault doctor --jsonLocal skill admitted before the signing key existed, or content rewritten outside the gate.Run autovault doctor --repair on unsigned local skills.

Where next

01Read the setup referenceFull flag list, the three adoption modes, and the TTY requirement.Open API reference →02Restart from Quick startInstall, run the setup wizard, scope your first skill end-to-end.Open quick start →03File an issueIf the recovery commands don't resolve it, open an issue against the autovault repo.Open GitHub →