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.
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.
Choose a setup path
Section titled “Choose a setup path”Option 1: Set up with the CLI
Section titled “Option 1: Set up with the CLI”Install the CLI, then follow the manual project setup.
Option 2: Set up with an AI coding agent
Section titled “Option 2: Set up with an AI coding agent”sourceorrery init --integration allUse 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.
Install
Section titled “Install”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 |
With a package manager
Section titled “With a package manager”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:
winget install --id Netizine.SourceOrrery --exactAlternatively, use Scoop (opens in a new tab) or the prebuilt download below:
scoop bucket add sourceorrery https://github.com/Netizine/scoop-sourceorreryscoop install sourceorreryThe 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.
brew install Netizine/sourceorrery/sourceorreryWith Homebrew on Linux (opens in a new tab):
brew install Netizine/sourceorrery/sourceorreryFrom the GitHub release
Section titled “From the GitHub release”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.
$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 $archiveInvoke-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.
Apple silicon shown. On an Intel Mac, use x86_64-apple-darwin in the
archive name instead of aarch64-apple-darwin.
set -eurelease=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-0.3.1-aarch64-apple-darwin
curl -fLO "$release/$archive.tar.gz"curl -fLO "$release/SHA256SUMS"awk -v file="$archive.tar.gz" '$2 == file { print }' SHA256SUMS > "$archive.sha256"test -s "$archive.sha256"shasum -a 256 -c "$archive.sha256"
tar xzf "$archive.tar.gz"sudo mkdir -p /usr/local/binsudo install "$archive/sourceorrery" /usr/local/bin/sourceorrery --helpThe binaries are not signed or notarised yet, so macOS may block a browser-downloaded binary. Verify the source and checksum before deciding whether to allow it in your system’s security settings.
x64 shown. On arm64, use aarch64-unknown-linux-gnu in the archive name
instead of x86_64-unknown-linux-gnu. The builds are for glibc 2.34 or
newer (Ubuntu 22.04, Debian 12, RHEL 9, Amazon Linux 2023 and later); musl systems such as Alpine are
not supported. Every platform’s minimum is in the
platform support.
set -eurelease=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-0.3.1-x86_64-unknown-linux-gnu
curl -fLO "$release/$archive.tar.gz"curl -fLO "$release/SHA256SUMS"awk -v file="$archive.tar.gz" '$2 == file { print }' SHA256SUMS > "$archive.sha256"test -s "$archive.sha256"sha256sum -c "$archive.sha256"
tar xzf "$archive.tar.gz"sudo install "$archive/sourceorrery" /usr/local/bin/sourceorrery --helpThe OS credential store on Linux is Secret Service over D-Bus. On a server or in a container there is none: the vault opens with its recovery key, as described in Headless: WSL, Docker, CI.
Shell completions are available with
sourceorrery completions bash|zsh|fish|powershell|elvish.
From the package registries
Section titled “From the package registries”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.
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.
From source
Section titled “From source”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.
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1python scripts/release/set-version.py 0.3.1 --keep-node-linkscargo install --locked --path crates/sourceorrery-clisourceorrery --helpOr 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.
Set up a project
Section titled “Set up a project”With the CLI installed, run the guided first run from your application’s directory:
sourceorrery setupThe 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.
First vault to first run
Section titled “First vault to first run”Run these steps from the directory containing your application. Use a development credential for the walkthrough.
-
Create a vault.
Terminal window sourceorrery vault create developmentThe vault is one SQLite file,
vaults/development.sorvault, under the SourceOrrery home directory (%LOCALAPPDATA%\sourceorreryon Windows,~/Library/Application Support/sourceorreryon macOS,~/.local/share/sourceorreryon 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. -
Store a secret.
Terminal window sourceorrery secret set database-password --vault developmentThe value is read from a hidden prompt, from stdin when piped, or from a file with
--from-file. There is no--valueoption: arguments leak into shell history and process listings. Everysetcreates 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 developmentsourceorrery secret set tls-key --from-file ./server.key --vault developmentNames are letters, digits and hyphens, at most 127 characters.
-
Inspect without revealing.
Terminal window sourceorrery secret list --vault developmentsourceorrery secret get database-password --vault developmentsourceorrery secret versions database-password --vault developmentAll 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 --revealAdd
-o jsonto any command for machine-readable output; errors then carry a stable error code. -
Declare what your project needs.
Terminal window sourceorrery initOn a terminal,
initlists the vault’s secrets to tick, adds any new ones the project needs and writessourceorrery.tomlnext to your code after a review (init --allor--secret NAMEwithout a terminal). It is the committed, value-free replacement for.env:[project]name = "my-application"vault = "development"[secrets.database-password]required = truepurpose = "Database authentication" # documentation onlyIf the project already has a manifest,
initadds to it in place.A
value = ...key, or any other unknown key, is a parse error. Keep actual credentials out of names, comments andpurposefields too: these remain plain text. Commit the reviewed manifest, then confirm every entry resolves without reading a secret value:Terminal window sourceorrery checkThe
database-passwordrow should showok. A missing or inaccessible required secret makes the command fail. Metadata checks are audited. -
Run your application with its secrets.
Terminal window sourceorrery run -- npm startReplace
npm startwith your application’s normal start command. For a Python program, for example, usesourceorrery run -- python app.py.Each declared secret is resolved and placed in the child’s environment,
database-passwordasDATABASE_PASSWORD(setenv = "..."in the manifest to choose another name). The parent never prints the values and a missing required secret aborts before the child starts.
Where to next
Section titled “Where to next”sourceorrery uiopens 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.
Bring an existing project
Section titled “Bring an existing project”- Import a
.envfile withsourceorrery 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,codexor another supported agent. These are workflow instructions, not a security boundary.
Updating
Section titled “Updating”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--versionselects 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 toPATHagain. - 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:
sourceorrery --versionAn 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.