---
generator: "vaultspec-marketing discovery"
title: "Install vaultspec-core - vaultspec-core documentation"
description: "For the full setup path and a working example, start at the documentation home. This page covers installation choices and updates."
url: "https://vaultspec.neve.md/docs/core/installation.html"
component: "vaultspec-core"

---

[View as Markdown](<https://vaultspec.neve.md/docs/core/installation.md>)

# Install vaultspec-core

For the full setup path and a working example, start at the [documentation home](<https://vaultspec.neve.md/docs/index.html>). This page covers installation choices and updates.

## Before you begin

Install [uv](<https://docs.astral.sh/uv/getting-started/installation/>). Open a terminal in the project you want to configure. Core does not need a GPU or an API key.

See [requirements](<https://vaultspec.neve.md/docs/requirements.html>) for supported Python versions and [distribution channels](<https://vaultspec.neve.md/docs/core/channels.html>) for other platforms and binary downloads.

## Install

Acquiring the package and provisioning a project are separate operations. `uvx` acquires and runs Core in an isolated environment; Core’s `install` command writes the workflow into the current project. Neither operation starts your agent.

**Command**

```sh
uvx vaultspec-core --version
uvx vaultspec-core install
uvx vaultspec-core doctor
```

Keep the `uvx` prefix for subsequent commands. This route does not put `vaultspec-core` on your shell’s PATH.

## What it writes

| Location | Purpose |
| --- | --- |
| `.vault/` | Research, decisions, plans, and other records |
| `.vaultspec/` | Workflow rules, skills, templates, and agent definitions |
| `.claude/`, `.codex/`, `.gemini/`, `.agents/` | Generated agent configuration |
| `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` | Instructions for supported agents |
| `.mcp.json` | Core’s MCP server entry |
| `.pre-commit-config.yaml` | Configuration for commit checks |
| `.gitignore`, `.gitattributes` | Managed ignore and line-ending rules |

Installing writes configuration; it does not open an agent session. Use [Connect your agent](<https://vaultspec.neve.md/docs/guides/mcp.html>) to check the connection.

## How you run it afterwards

| Installation | Run commands as |
| --- | --- |
| Run on demand with uvx | `uvx vaultspec-core status` |
| Install a shell tool | `vaultspec-core status` |
| Add a project dependency | `uv run vaultspec-core status` |

To install a shell tool:

**Command**

```sh
uv tool install vaultspec-core
```

Follow uv’s PATH instructions if your shell cannot find the installed command. Installing the tool and configuring a project are separate operations: run `vaultspec-core install` in each project that needs the workflow.

## Joining a project that already has it

Use the command prefix selected by the project. In a checkout already provisioned on this machine, `uv sync` installs locked project dependencies and `uv run vaultspec-core status` checks its records. For a fresh clone, follow the project’s setup instructions; the joining check here covered an existing checkout.

### Choose a provisioning mode

Package installation makes the command available. Provisioning writes the project’s vault and agent configuration. Choose placement independently:

| Mode | Intended package setup | Generated launch prefix |
| --- | --- | --- |
| `tool` | Package acquired outside the project | `uvx --from vaultspec-core` |
| `dev` | Project’s default development dependency group | `uv run --no-sync` |
| `dependency` | Project runtime dependencies | `uv run --no-sync` |

Core chooses the mode from an explicit `--mode`, then a saved workspace choice, then the package’s placement in `pyproject.toml`, then `tool`. Invoking Core through `uvx` does not force `tool` mode in a project that declares it as a dependency. The interpreter must also belong to the workspace before Core can read its TypeSafe key from the workspace-root `.env`.

For development tooling in a uv-managed Python project:

**Command**

```sh
uv add --dev vaultspec-core
uv run vaultspec-core install --mode dev
uv run vaultspec-core status
```

The `--mode dev` and `--mode dependency` flags configure how agent commands launch Core. `uv add --dev` installs the development dependency; neither mode flag adds a package to your project. This mode also affects eligibility to read the project’s `.env`; see [environment loading](<https://vaultspec.neve.md/docs/guides/typesafe-env.html#which-source-wins>).

## Preview before writing

**Command**

```sh
uvx vaultspec-core install --dry-run
```

Review the reported paths before installing into a project with existing agent configuration. For provider selection and skip options, use the [CLI reference](<https://vaultspec.neve.md/docs/core/cli.html>).

## Verify the install

**Command**

```sh
uvx vaultspec-core doctor
uvx vaultspec-core status
```

On a fresh installation, `doctor` exits `0` with `framework ok` and clean vault checks; it exits `1` for warnings and `2` for errors. Status reports no features or plans until a record is created.

`semantic search none` means vaultspec-rag is not provisioned yet; Core still creates and lists records. [Install vaultspec-rag](<https://vaultspec.neve.md/docs/rag/installation.html>) next. See [workspace verification](<https://vaultspec.neve.md/docs/core/verification.html>) for other findings.

Commit-hook configuration does not demonstrate that Git is running those hooks. Follow your project’s hook setup and the [verification guide](<https://vaultspec.neve.md/docs/core/verification.html>).

## Upgrade

Save or commit your project changes before refreshing bundled files. First update the package using the route that acquired it:

| Package route | Update command |
| --- | --- |
| Run on demand with uvx | `uvx --upgrade vaultspec-core --version` |
| Standalone uv tool | `uv tool upgrade vaultspec-core` |
| uv project dependency | `uv sync --upgrade-package vaultspec-core` |
| Scoop | `scoop update vaultspec-core` |
| Homebrew | `brew upgrade vaultspec-core` |

Then refresh each project’s provisioned files. For the uvx route, run:

**Command**

```sh
uvx vaultspec-core install --upgrade
```

`install --upgrade` refreshes the project from the package you are running; it does not upgrade that package. Use the matching command prefix for other routes. Review the changed files and run `doctor` again.

### Environment settings during install and upgrade

Set environment variables in the process running `install` or `install --upgrade`. The workspace-root `.env` is not a general settings file: Core reads only its TypeSafe key there, and only from an eligible project environment.

To save supported settings for later Core commands, explicitly import them with `--env NAME` or `--env-file PATH`. On an existing installation, include `--upgrade`:

**Usage synopsis**

```sh
uvx vaultspec-core install --upgrade --env VAULTSPEC_CORE_TYPESAFE_API_KEY
```

This imports a key already set in the process environment into `.vaultspec/.env`; it does not require a key for installation. See [when settings take effect](<https://vaultspec.neve.md/docs/guides/typesafe-env.html#during-install-and-upgrade>) for import timing and precedence.

Plain `install` on an existing installation is rejected as already installed. Invalid Vaultspec settings normally refuse the run and name the variable; fix or unset it. The watchdog switch is the exception: an unrecognised `VAULTSPEC_STDIO_WATCHDOG` value leaves it armed. The [environment variables](<https://vaultspec.neve.md/docs/core/cli.html#environment-variables>) list each accepted value. For other package managers, migrations, or removal, consult the [CLI reference](<https://vaultspec.neve.md/docs/core/cli.html>) and [distribution channels](<https://vaultspec.neve.md/docs/core/channels.html>).

## Where to go next

- [Create your first record](<https://vaultspec.neve.md/docs/index.html#create-your-first-record>).
- [Install vaultspec-rag](<https://vaultspec.neve.md/docs/rag/installation.html>).
- [Connect your agent](<https://vaultspec.neve.md/docs/guides/mcp.html>).
- [Run a feature](<https://vaultspec.neve.md/docs/guides/workflow.html>).
- [Configure TypeSafe and environment loading](<https://vaultspec.neve.md/docs/guides/typesafe-env.html>).