Skip to content

Getting started

Install SourceOrrery 0.3.1 with Homebrew or WinGet, a prebuilt release, Cargo or source, create an encrypted vault, store a secret without ever typing it on a command line, and run your application with secrets in its environment.

12 min read

SourceOrrery 0.3.1 is an encrypted local vault with a cloud-secrets-manager-style lifecycle, a CLI with an interactive vault manager, and read-only SDKs for Python, JavaScript/TypeScript, Rust, Java, .NET, Go, C, C++ and PHP. It works on Windows, macOS and Linux.

Install the CLI, then follow the manual project setup.

Terminal window
sourceorrery init --integration all

Use your existing coding agent and ask: “Set up SourceOrrery for this project without showing secret values.” Replace all with your agent’s name to install only its skills. The agent handles the manifest, code and launch commands; you create vaults and enter values privately. The agent setup guide also covers updating skills from the repository independently of the CLI.

There are three ways to install 0.3.1: the published packages, the files on the GitHub release, or a build from source.

Your starting point Recommended route
macOS or Linux with Homebrew Homebrew: no Rust toolchain needed
Windows WinGet: no Rust toolchain needed
No supported package manager Prebuilt release download
Rust and a C compiler already installed Cargo
Contributing or changing the implementation Build from source

Each package manager downloads the CLI archive from the GitHub release and checks its SHA-256 against the one recorded at release time, so what it installs is the released file.

With WinGet:

Terminal window
winget install --id Netizine.SourceOrrery --exact

Alternatively, use Scoop (opens in a new tab) or the prebuilt download below:

Terminal window
scoop bucket add sourceorrery https://github.com/Netizine/scoop-sourceorrery
scoop install sourceorrery

The binaries are not code-signed yet, so SmartScreen may ask the first time sourceorrery runs (More info → Run anyway); the hash check above, the release’s SHA256SUMS and gh attestation verify are how to check a download in the meantime.

The v0.3.1 release (opens in a new tab) ships the CLI for Windows, macOS and Linux on x64 and arm64, the C ABI library with its headers, and every SDK package (wheels, the npm tarballs, the jar, the NuGet package), with a SHA256SUMS file to check each download against.

In PowerShell. On Windows on Arm, use aarch64-pc-windows-msvc in the archive name instead of x86_64-pc-windows-msvc.

Terminal window
$ErrorActionPreference = "Stop"
$release = "https://github.com/Netizine/sourceorrery/releases/download/v0.3.1"
$archive = "sourceorrery-0.3.1-x86_64-pc-windows-msvc.zip"
$dir = "$env:LOCALAPPDATA\Programs\sourceorrery"
Invoke-WebRequest "$release/$archive" -OutFile $archive
Invoke-WebRequest "$release/SHA256SUMS" -OutFile SHA256SUMS
$pattern = '^[a-fA-F0-9]{64}\s+\*?' + [regex]::Escape($archive) + '$'
$entry = @(Get-Content SHA256SUMS | Where-Object { $_ -match $pattern })
if ($entry.Count -ne 1) { throw "Missing or ambiguous checksum for $archive" }
$expected = ($entry[0] -split '\s+')[0]
if ((Get-FileHash $archive -Algorithm SHA256).Hash -ne $expected) {
throw "Checksum mismatch; do not extract this download"
}
Expand-Archive $archive -DestinationPath $dir -Force
[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path', 'User'));$dir", "User")

Open a new terminal and run sourceorrery --help.

Shell completions are available with sourceorrery completions bash|zsh|fish|powershell|elvish.

The CLI is on crates.io, and Cargo builds and installs it in one step. You need Rust 1.91.1 or newer and a C compiler for the bundled SQLite (on Linux also libdbus-1-dev and pkg-config for the Secret Service); Building from source has the commands to install them on each platform.

Terminal window
cargo install --locked sourceorrery-cli --version 0.3.1

--locked builds with the exact dependency versions the release was tested with, from the lock file inside the crate; without it, Cargo picks the newest compatible version of every dependency at install time.

The SDKs are published as packages for each language:

Language Package Install
Python sourceorrery (opens in a new tab) on PyPI pip install sourceorrery==0.3.1
JavaScript / TypeScript @sourceorreryai/sdk (opens in a new tab) on npm npm install @sourceorreryai/sdk@0.3.1
Rust sourceorrery (opens in a new tab) on crates.io cargo add sourceorrery@0.3.1
Java ai.sourceorrery:sourceorrery (opens in a new tab) on Maven Central <version>0.3.1</version> (see Java)
.NET SourceOrrery (opens in a new tab) on NuGet dotnet add package SourceOrrery --version 0.3.1
Go github.com/netizine/sourceorrery/bindings/go (opens in a new tab) go get github.com/netizine/sourceorrery/bindings/go@v0.3.1
PHP sourceorrery/sourceorrery (opens in a new tab) on Packagist composer require sourceorrery/sourceorrery:0.3.1

Go, C, C++ and PHP load the C ABI library from the release (below); each SDK page has the steps. How every package is published, and how to check that what you installed is what was released, is in Supply chain.

With Git, Python 3.11 or newer for version stamping, Rust 1.91.1 or newer, a C compiler, and on Linux libdbus-1-dev and pkg-config, build from the repository and install the CLI into ~/.cargo/bin, which rustup put on your PATH.

Check out the v0.3.1 tag to build the published release source.

Terminal window
git clone https://github.com/Netizine/sourceorrery
cd sourceorrery
git checkout v0.3.1
python scripts/release/set-version.py 0.3.1 --keep-node-links
cargo install --locked --path crates/sourceorrery-cli
sourceorrery --help

Or build without installing: cargo build --release -p sourceorrery-cli leaves the binary at target/release/sourceorrery (sourceorrery.exe on Windows). Building from source covers the C ABI, every SDK and the test suites.

With the CLI installed, run the guided first run from your application’s directory:

Terminal window
sourceorrery setup

The screens make the vault: its name, this machine’s key in the OS credential store and a recovery key shown once, an optional view check (a password, and an authenticator code on top, asked before anyone views the vault or reveals a value), and where it keeps secrets: its own file, or HashiCorp Vault, AWS Secrets Manager or Azure Key Vault through a connection it holds. Nothing is written until the review confirms. First run walks through each step; sourceorrery setup --guide prints the one command that does the same where there is no terminal. The sections below are the manual path.

sourceorrery setupFull size
1 / 12StartWith no vault yet, setup offers to create one. This machine's key goes into its credential store, so this machine opens the vault without asking.

Run these steps from the directory containing your application. Use a development credential for the walkthrough.

  1. Create a vault.

    Terminal window
    sourceorrery vault create development

    The vault is one SQLite file, vaults/development.sorvault, under the SourceOrrery home directory (%LOCALAPPDATA%\sourceorrery on Windows, ~/Library/Application Support/sourceorrery on macOS, ~/.local/share/sourceorrery on Linux). Every value in it is encrypted with a vault key that never touches the disk in the clear.

    The vault key is kept twice: as this machine’s key in the OS credential store (Windows Credential Manager, macOS Keychain, Secret Service), so there is nothing to type later, and under the vault’s recovery key, which the command prints once (or writes to --recovery-key-out FILE). Keep it apart from this machine: it opens the vault anywhere else, and nothing else does when this machine’s key is gone.

  2. Store a secret.

    Terminal window
    sourceorrery secret set database-password --vault development

    The value is read from a hidden prompt, from stdin when piped, or from a file with --from-file. There is no --value option: arguments leak into shell history and process listings. Every set creates a new, immutable version.

    Terminal window
    # From a pipe or a file (one trailing newline from stdin is stripped)
    printf '%s' "$DB_PASSWORD" | sourceorrery secret set database-password --vault development
    sourceorrery secret set tls-key --from-file ./server.key --vault development

    Names are letters, digits and hyphens, at most 127 characters.

  3. Inspect without revealing.

    Terminal window
    sourceorrery secret list --vault development
    sourceorrery secret get database-password --vault development
    sourceorrery secret versions database-password --vault development

    All three print metadata only: version id, status, content type, tags, timestamps. Disclosure is a deliberate, audited act:

    Terminal window
    sourceorrery secret get database-password --vault development --reveal

    Add -o json to any command for machine-readable output; errors then carry a stable error code.

  4. Declare what your project needs.

    Terminal window
    sourceorrery init

    On a terminal, init lists the vault’s secrets to tick, adds any new ones the project needs and writes sourceorrery.toml next to your code after a review (init --all or --secret NAME without a terminal). It is the committed, value-free replacement for .env:

    [project]
    name = "my-application"
    vault = "development"
    [secrets.database-password]
    required = true
    purpose = "Database authentication" # documentation only

    If the project already has a manifest, init adds to it in place.

    A value = ... key, or any other unknown key, is a parse error. Keep actual credentials out of names, comments and purpose fields too: these remain plain text. Commit the reviewed manifest, then confirm every entry resolves without reading a secret value:

    Terminal window
    sourceorrery check

    The database-password row should show ok. A missing or inaccessible required secret makes the command fail. Metadata checks are audited.

  5. Run your application with its secrets.

    Terminal window
    sourceorrery run -- npm start

    Replace npm start with your application’s normal start command. For a Python program, for example, use sourceorrery run -- python app.py.

    Each declared secret is resolved and placed in the child’s environment, database-password as DATABASE_PASSWORD (set env = "..." in the manifest to choose another name). The parent never prints the values and a missing required secret aborts before the child starts.

  • sourceorrery ui opens the interactive vault manager: dashboards, secrets and their versions, where each is kept, the projects built from the vault, deleted secrets and the audit log, all without ever showing a value (CLI reference).
  • SDKs to read the same secrets from Python, JavaScript/TypeScript, Rust, Java, .NET, Go, C, C++ or PHP.
  • CLI reference for every command and option, including soft delete, recovery, time windows and the audit log.
  • Headless: WSL, Docker, CI when there is no OS credential store or no terminal.
  • Vault format if you want to know exactly what is on disk.
  • Import a .env file with sourceorrery import .env, then check the results before removing the original plaintext file. The command does not delete it.
  • Install skills for AI coding agents with sourceorrery init --integration claude, cursor, codex or another supported agent. These are workflow instructions, not a security boundary.

SourceOrrery deliberately has no update checks or automatic updater. When you choose to update, open the latest release (opens in a new tab) and read its release notes, then use your original installation method:

  • Cargo: run cargo install --locked sourceorrery-cli. Leaving out --version selects the latest published version; Cargo replaces an older installation. Keep any feature flags you used for a headless build.
  • Release archive: follow the download and checksum steps with the new version in place of 0.3.1. Close the CLI and interactive manager before replacing the executable in its existing installation directory. On Windows, skip adding that directory to PATH again.
  • Source: follow From source with the new release tag and matching version-stamping argument, then reinstall the CLI. The build guide covers custom builds.

Confirm which version your terminal runs:

Terminal window
sourceorrery --version

An update keeps your vault files and OS credential-store entries. A release that changes the vault format says so in its notes and refuses a file from an earlier release with migration_required, never changing it: Upgrading keeps that file for the release that wrote it and moves its secrets into a vault made by the new one.

SDKs update separately through your application’s package manager. For example, use python -m pip install --upgrade sourceorrery in your Python environment, or npm install @sourceorreryai/sdk@latest in your JavaScript/TypeScript project. Update any pinned dependency versions and regenerate lockfiles through your package manager. Check your SDK guide for native-library requirements, then test your application.