Getting started

SourceOrrery is at milestone 2: an encrypted local vault with an Azure Key Vault–style lifecycle, a CLI, and read-only SDKs for Python, JavaScript/TypeScript, Rust, Java, .NET, Go, C, C++ and PHP. It works today on Windows, macOS and Linux. It has not been audited; do not treat it as a production secret store yet.

Install

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

From the package registries

The CLI is on crates.io, and Cargo builds and installs it in one step. You need Rust 1.88 or newer and a C compiler for the bundled SQLite (on Linux also libdbus-1-dev and pkg-config for the Secret Service):

cargo install sourceorrery-cli

The SDKs are published as packages for each language:

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

Go, C, C++ and PHP load the C ABI library from the release (below); each SDK page has the steps.

From the GitHub release

The v0.1.3 release 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. Homebrew, WinGet and Scoop packages are on the roadmap.

Windows

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

$release = "https://github.com/Netizine/sourceorrery/releases/download/v0.1.3"
$archive = "sourceorrery-0.1.3-x86_64-pc-windows-msvc.zip"
$dir = "$env:LOCALAPPDATA\Programs\sourceorrery"

Invoke-WebRequest "$release/$archive" -OutFile $archive
Invoke-WebRequest "$release/SHA256SUMS" -OutFile SHA256SUMS
Select-String (Get-FileHash $archive -Algorithm SHA256).Hash.ToLower() SHA256SUMS   # prints the matching line, or nothing

Expand-Archive $archive -DestinationPath $dir -Force
[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path', 'User'));$dir", "User")

Open a new terminal and run sourceorrery --help.

macOS

Apple silicon shown. On an Intel Mac, use x86_64-apple-darwin in the archive name instead of aarch64-apple-darwin.

release=https://github.com/Netizine/sourceorrery/releases/download/v0.1.3
archive=sourceorrery-0.1.3-aarch64-apple-darwin

curl -LO "$release/$archive.tar.gz"
curl -LO "$release/SHA256SUMS" && shasum -a 256 -c --ignore-missing SHA256SUMS

tar xzf "$archive.tar.gz"
sudo install "$archive/sourceorrery" /usr/local/bin/
sourceorrery --help

The binaries are not signed or notarised yet (that is on the roadmap). A file downloaded with a browser rather than curl carries the quarantine attribute; clear it with xattr -d com.apple.quarantine <file> before unpacking.

Linux

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-based distributions.

release=https://github.com/Netizine/sourceorrery/releases/download/v0.1.3
archive=sourceorrery-0.1.3-x86_64-unknown-linux-gnu

curl -LO "$release/$archive.tar.gz"
curl -LO "$release/SHA256SUMS" && sha256sum -c --ignore-missing SHA256SUMS

tar xzf "$archive.tar.gz"
sudo install "$archive/sourceorrery" /usr/local/bin/
sourceorrery --help

The OS credential store on Linux is Secret Service over D-Bus. On a server or in a container there is none: use a passphrase protector, as described in Headless: WSL, Docker, CI.

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

From source

With the same requirements as cargo install above (Rust 1.88 or newer, a C compiler, and on Linux libdbus-1-dev and pkg-config), build the release tag from the repository:

git clone --branch v0.1.3 https://github.com/Netizine/sourceorrery
cd sourceorrery
cargo build --release
./target/release/sourceorrery --help

Put target/release/sourceorrery (sourceorrery.exe on Windows) on your PATH.

Note

Headless servers without a credential store can build without OS-keyring support and use passphrase protectors only:

cargo build --release -p sourceorrery-cli --no-default-features

See Headless: WSL, Docker, CI.

First vault to first run

1. Create a vault.

   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.

   By default the vault key is protected by the OS credential store (Windows Credential Manager, macOS Keychain, Secret Service), so there is nothing to type later. Where no store is available, or with --protector passphrase, you are asked for a passphrase twice and the key is derived from it with Argon2id.

2. Store a secret.

   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.

   # 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 follow Azure Key Vault rules: letters, digits and hyphens, at most 127 characters.

3. Inspect without revealing.

   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:

   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.

   sourceorrery init

   This writes sourceorrery.toml next to your code. 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

   A value = ... key, or any other unknown key, is a parse error. Commit the manifest; it holds nothing to protect. Then confirm every entry resolves without reading a single value:

   sourceorrery check

5. Run your application with its secrets.

   sourceorrery run -- npm start

   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.

What this does not protect against

Environment variables are visible to any process that can read the child process’s environment, and anything already running as your OS user can unlock the same vault and call get --reveal exactly as you can. SourceOrrery removes plaintext from disk and from the repository and puts every access on the record; it does not isolate your secrets from code running with your privileges. The threat model keeps those three guarantees separate.

Where to next

• 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.