Install vaultspec-coreLink to Install vaultspec-core
For the full setup path and a working example, start at the documentation home. This page covers installation choices and updates.
Before you beginLink to Before you begin
Install uv. Open a terminal in the project you want to configure. Core does not need a GPU or an API key.
See requirements for supported Python versions and distribution channels for other platforms and binary downloads.
InstallLink to 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
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 writesLink to What it writes
Location |
Purpose |
|---|---|
|
Research, decisions, plans, and other records |
|
Workflow rules, skills, templates, and agent definitions |
|
Generated agent configuration |
|
Instructions for supported agents |
|
Core’s MCP server entry |
|
Configuration for commit checks |
|
Managed ignore and line-ending rules |
Installing writes configuration; it does not open an agent session. Use Connect your agent to check the connection.
How you run it afterwardsLink to How you run it afterwards
Installation |
Run commands as |
|---|---|
Run on demand with uvx |
|
Install a shell tool |
|
Add a project dependency |
|
To install a shell tool:
Command
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 itLink to 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 modeLink to Joining a project that already has it, 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 |
|---|---|---|
|
Package acquired outside the project |
|
|
Project’s default development dependency group |
|
|
Project runtime dependencies |
|
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
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.
Preview before writingLink to Preview before writing
Command
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.
Verify the installLink to Verify the install
Command
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 next.
See workspace verification 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.
UpgradeLink to 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 |
|
Standalone uv tool |
|
uv project dependency |
|
Scoop |
|
Homebrew |
|
Then refresh each project’s provisioned files. For the uvx route, run:
Command
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 upgradeLink to Upgrade, 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
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
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 list each accepted value.
For other package managers, migrations, or removal, consult the
CLI reference and distribution channels.