Vault -- Secret Management | ASD Documentation

Alpha Feature — Vault is ready for testing and daily use, but the API may change between releases. If you encounter issues, please report them via GitHub.

Requires a paid plan. Vault is available starting with the Developer plan. The Free plan does not include Vault access. You must be logged in (asd login) to use Vault commands.

What is ASD Vault?

ASD Vault provides encrypted secret management backed by Supabase Vault and pgsodium. Instead of scattering API keys, database passwords, and certificates across .env files, sticky notes, and chat messages, Vault gives you a single encrypted store that you can access from the CLI, inject into running processes, and share securely with your team.

Secrets are encrypted at rest using pgsodium AEAD (XChaCha20-Poly1305). The encryption root key is managed by Supabase KMS and never stored in the database. Access is enforced via Row Level Security per user and organisation.

Quick Start

# Sign in (required before using Vault)
asd login

# Store a secret
asd vault set DATABASE_URL "postgres://user:pass@host:5432/db"

# Retrieve a secret
asd vault get DATABASE_URL

# List all secrets (shows metadata only, never values)
asd vault list

That is all you need to get started. The sections below cover every Vault capability in detail.

Commands Reference

Command	Description
`asd vault list`	List secrets (name, category, scope — no values shown)
`asd vault get <name>`	Print decrypted value to stdout
`asd vault set <name> [value]`	Create or update a secret
`asd vault delete <name>`	Soft-delete a secret
`asd vault import <directory>`	Bulk import secrets from a directory
`asd vault export <directory>`	Export all secrets to files
`asd vault inject <template>`	Substitute `asd://` references in a template file
`asd vault run --env-file <tpl> -- <cmd>`	Run a command with secrets injected as environment variables

Storing Secrets

From a Command Argument

The simplest way to store a secret:

asd vault set API_KEY "sk-abc123"

From Standard Input

For multiline values or piped content, use --stdin:

cat ~/.kube/config | asd vault set kubeconfig --stdin

From a File

Store the contents of a file directly:

asd vault set tls/cert --file ./cert.pem

With Metadata

Add a category and description to keep your secrets organised:

asd vault set db/PASSWORD "s3cret" 
  --category database 
  --description "Production DB password"

Categories are free-form strings. Use them to group related secrets (e.g., database, api, tls) so they are easier to find with asd vault list.

Retrieving Secrets

asd vault get prints the decrypted value to stdout with no extra formatting, making it safe to use in scripts and pipelines:

# Use in a script
DB_URL=$(asd vault get DATABASE_URL)

# Pipe to another command
asd vault get tls/cert > /tmp/cert.pem

asd vault list shows metadata only (name, category, scope) and never displays decrypted values. This is safe to run in shared terminals or screen-sharing sessions.

Injecting Secrets into Processes

Running Commands with Secrets

The asd vault run command injects secrets as environment variables into a child process. Create a template file that references your secrets:

# .env.tpl
DATABASE_URL=asd://db/PASSWORD
API_KEY=asd://API_KEY
REDIS_URL=asd://cache/REDIS_URL

Then run your application with those secrets injected:

asd vault run --env-file .env.tpl -- node server.js

Vault resolves every asd:// reference, injects the decrypted values as environment variables, and starts your command. The secrets exist only in the process environment — they are never written to disk.

Substituting References in Config Files

For configuration files that need secrets baked in (e.g., JSON, YAML):

asd vault inject config.tpl config.json

This reads config.tpl, replaces all asd://secret-name references with their decrypted values, and writes the result to config.json.

Import and Export

Importing Secrets

Bulk-import secrets from a directory where each file name becomes the secret name:

asd vault import ./secrets/

If the directory contains files like API_KEY, DB_PASSWORD, and TLS_CERT, each file’s contents become the corresponding secret value.

Exporting Secrets

Export all your secrets back to files for backup or migration:

asd vault export ./backup/

The export is round-trip faithful — importing an exported directory recreates the original secrets.

Scopes: Personal vs Organisation

Every secret has a scope that determines who can access it:

Scope	Flag	Who Can Access
Personal	`--scope user` (default)	Only you
Organisation	`--scope org`	You and your organisation’s admins

# Personal secret (default)
asd vault set MY_TOKEN "abc123"

# Shared with your organisation
asd vault set SHARED_API_KEY "xyz789" --scope org

Organisation-scoped secrets are ideal for shared credentials that multiple team members need, such as staging environment tokens or third-party API keys.

Plan Limits

Vault availability and capacity depend on your subscription plan:

Plan	Secrets Included	Vault Access
Free	0	Not available
Developer	10	Included
Pro	50	Included
Scale	200	Included
Enterprise	Unlimited	Included

Need more secrets? The Vault addon adds 50 additional secrets for EUR 5/month per unit. Manage addons from your billing page.

Vault is available starting with the Developer plan. If you need encrypted secret management for a larger team, the Pro plan and above provide higher limits along with organisation-scoped sharing.

Web Dashboard

You can also manage secrets through the web interface at /workspace/vault/. The dashboard lets you browse, create, and delete secrets with a visual interface.

For security, the web dashboard shows secret metadata (name, category, scope, creation date) but never displays decrypted values. To read a secret’s value, use asd vault get from the CLI.

Security Details

ASD Vault is designed with a zero-plaintext-on-disk philosophy:

Encryption at rest: Secrets are encrypted using pgsodium AEAD (XChaCha20-Poly1305) before being stored in the database.
Key management: The encryption root key is managed by Supabase KMS and never stored alongside the encrypted data.
Access control: Row Level Security (RLS) policies enforce that users can only access their own secrets, or organisation-scoped secrets they are authorised for.
Soft deletes: When you delete a secret, it is soft-deleted (marked with a deleted_at timestamp) rather than permanently removed, providing an audit trail.
No plaintext on disk: Decrypted values are only held in memory during retrieval and injection. They are never written to log files or temporary storage.

Related Guides

Security and Authentication — Protect services with Basic Auth and tunnel tokens
CLI Command Reference — Full CLI reference including Vault commands