Docs

Project linking

Every key belongs to a project, so every command needs to know which project it is working in. Link a directory once and the CLI picks the project up from there.

Linking a directory

Run apivault link from the root of your repository with the project's ID or slug. It writes the binding to .apivault.json in that directory.

LinkShell
# Find the project's ID or slug
apivault projects list

# Bind the current directory to it
apivault link <id>

apivault projects use <id> does the same thing, and with --global sets the fallback project for directories that are not linked. apivault unlink removes the binding. All of these are covered on the apivault projects page.

How the project is chosen

Each command uses the first of these that is set:

  1. The -p, --project flag
  2. The APIVAULT_PROJECT environment variable
  3. A local project file in the current directory
  4. The global fallback in ~/.apivault/config.json

Only the current directory is checked for a local file — parent directories are not searched — so run commands from the directory you linked. To see which project a command will use and where that came from:

CheckShell
apivault projects current

The local project file

The CLI writes .apivault.json, and also reads .apivaultrc, apivault.json or .apivault if one of those exists instead. A file that holds only a project ID, rather than JSON, is read as that ID.

The same file holds any local defaults saved with apivault config set --local, such as run.env and run.command.

.apivault.jsonJSON
{
  "project": "my-app",
  "run": {
    "env": "Development",
    "command": "npm run dev"
  }
}

Linking in CI

A service token belongs to exactly one project, so a pipeline authenticated with APIVAULT_TOKEN needs no link at all. See CI/CD & service tokens.