Vaultarq

A developer-first, invisible secrets manager that replaces .env files and injects secrets into any shell or application without changing the code.

Vaultarq allows developers to store secrets once and access them instantly in any shell-based environment (Bash, Zsh, CI, Docker, etc.). It replaces the need for .env files by generating export-ready scripts securely from an encrypted vault file.

Features

• Zero friction: Works seamlessly with any shell environment (Bash, Zsh, CI/CD)
• Encrypted storage: AES-256-GCM encryption with Argon2id key derivation
• Environment isolation: Easily switch between dev, staging, prod environments
• Shell-friendly: Focus on bash-first workflows
• Portable: One self-contained CLI tool
• Secure by default: No secrets in plain text, only encrypted at rest
• Multi-language SDKs: Native integration for Node.js, Python, Rust, and Go

CLI and SDK Synchronization

Vaultarq consists of both a CLI tool and language-specific SDKs for Rust, Node.js, Python, and Go. These components work together to provide a seamless secrets management experience.

How It Works

The CLI tool manages the vault creation, secret storage, and environment switching. The SDKs integrate with your applications to read secrets from the vault created by the CLI.

Checking Synchronization

To ensure all components are working together properly, run:

./sync_check.sh

This script verifies that:

• The CLI is properly installed
• All SDKs have compatible vault formats
• Versions are synchronized across components
• SDKs can detect and interact with the CLI

Updating Versions

When releasing a new version, you can use the version updater to maintain consistency:

./update_versions.sh 0.2.0  # Replace with your version

This script updates version numbers across all components:

• CLI tool
• Rust SDK
• Node.js SDK
• Python SDK
• Go SDK
• CHANGELOG.md

SDK Usage

Each SDK provides a consistent API for interacting with Vaultarq:

// Rust
if vaultarq::is_available() {
    vaultarq::init()?;
}

// Node.js
if (vaultarq.isAvailable()) {
    await vaultarq.init();
}

# Python
if vaultarq.is_available():
    vaultarq.init()

// Go
if vaultarq.IsAvailable() {
    vaultarq.Init()
}

For more information, see CLI_SDK_SYNC.md.

Installation

Quick Install (recommended)

curl -fsSL https://raw.githubusercontent.com/Vaultarq/vaultarq/main/docker-install.sh | bash

This installs Vaultarq to ~/.local/bin/vaultarq by default. You can specify a different install location:

curl -fsSL https://raw.githubusercontent.com/Vaultarq/vaultarq/main/docker-install.sh | bash -s -- /usr/local/bin

Docker Installation

docker run --rm -v "${HOME}/.vaultarq:/root/.vaultarq" ghcr.io/vaultarq/cli:latest init

Manual Installation

git clone https://github.com/Vaultarq/vaultarq.git
cd vaultarq
./install.sh

Quick Start

1. Create a new vault:

   vaultarq init

   You'll be prompted to set a master password.

2. Add secrets:

   vaultarq push API_KEY=abc123
   vaultarq push DB_PASSWORD=supersecure

3. Load secrets into your shell:

   vaultarq pull
   source env/env.sh

4. Or use directly in a command:

   eval "$(vaultarq export --bash)"
   node app.js

5. Switch environments:

   vaultarq link prod
   vaultarq push API_KEY=prod_abc123

Usage Examples

Working with Multiple Environments

# Create a new vault
vaultarq init

# Add dev secrets (dev is the default environment)
vaultarq push API_KEY=dev_key
vaultarq push DB_PASS=dev_pass

# Switch to prod environment
vaultarq link prod

# Add prod secrets
vaultarq push API_KEY=prod_key
vaultarq push DB_PASS=prod_pass

# View available secrets
vaultarq list

# View secret values (be careful!)
vaultarq list --values

Using in CI/CD Pipeline

# In your CI script
echo "$VAULT_PASSWORD" | vaultarq pull
source env/env.sh
npm run test

Injecting Into Docker Containers

# Build with env vars
docker build -t myapp .

# Run with env vars from vaultarq
docker run --rm -it $(vaultarq export --dotenv | xargs -I{} echo "-e {}") myapp

Language SDKs

Vaultarq provides official SDKs for multiple programming languages, making it easy to integrate with your application without changing any code.

Node.js SDK

# Install from npm
npm install @vaultarq/node

// Use in your code
import vaultarq from '@vaultarq/node';

// Load secrets into process.env
await vaultarq.load();

// Now use secrets from process.env
console.log(process.env.API_KEY);

Python SDK

# Install from PyPI
pip install vaultarq

# Use in your code
from vaultarq import load_env

# Load secrets into os.environ
load_env()

# Now use secrets from os.environ
import os
print(os.environ["API_KEY"])

Rust SDK

# Add to your Cargo.toml
[dependencies]
vaultarq = "0.1.0"

// Use in your code
use vaultarq::init;

fn main() {
    // Load secrets into environment variables
    init().unwrap();
    
    // Now use secrets from environment
    println!("API_KEY: {}", std::env::var("API_KEY").unwrap_or_default());
}

Go SDK

# Add to your project
go get github.com/Vaultarq/go

// Use in your code
package main

import (
    "fmt"
    "os"
    
    "github.com/Vaultarq/go"
)

func main() {
    // Load secrets into environment variables
    vaultarq.Load()
    
    // Now use secrets from environment
    fmt.Println("API_KEY:", os.Getenv("API_KEY"))
}

Command Reference

Command	Description
vaultarq init	Create a new encrypted vault
vaultarq push KEY=VALUE	Add/update secrets to the vault
vaultarq pull	Load secrets into current shell
vaultarq export	Output secrets as export VAR=value statements
vaultarq link ENV	Set active environment (dev/prod/etc.)
vaultarq list	List secrets in vault
vaultarq open	Show vault path or current env info

Security

• All secrets are stored in an encrypted vault file using AES-256-GCM
• Master password is never stored; must be entered for each operation
• Password-derived key using Argon2id with memory-hard KDF
• Vault file is protected against tampering with GCM authentication
• Only temporary exports to memory or shell-sourced files

Vault Storage

• Local encrypted file: ~/.vaultarq/vault.json.enc
• JSON structure per environment:

  {
    "dev": { "STRIPE_KEY": "...", "DB_PASS": "..." },
    "prod": { "STRIPE_KEY": "...", "DB_PASS": "..." }
  }

Requirements

• Bash
• Node.js (for encryption/decryption)
• jq (for JSON manipulation)

License

MIT

Author

Dedan Okware (softengdedan@gmail.com)