Skip to content
kazuhideokiPublic

About

A lightweight CLI for mounting secret files into your workspace only when needed.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

88 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Veil

Veil is a lightweight CLI for personal secret file management on macOS. It keeps files like .env and service account JSONs out of your workspace by default, stores them in a dedicated location, and makes them appear only when you need them.

The Problem

In small personal projects, secret files often live directly in the workspace. That is convenient, but it creates a few recurring problems:

  • You can accidentally stage or commit secrets.
  • Coding agents and helper tools can always read plaintext files sitting in the repo.
  • Syncing secrets across multiple Macs becomes a manual and messy process.
  • Temporary files tend to stay around longer than intended.

Veil is meant to solve this without introducing a heavy secret management platform.

The Approach

Veil uses a simple model:

  • Store the real secret files outside the workspace in 1Password.
  • Materialize them into the workspace only when needed.
  • Remove materialized files explicitly, or clean up expired files with the TTL cleaner.

For the application or tool using the file, nothing special changes. It still sees the file at the usual path. The default store backend keeps each secret file as a 1Password Document and materializes files into the workspace only while you need them.

Example Workflow

# initialize workspace (and global config initially) 
veil init

# move an existing secret file into Veil management
veil add .env

# move all direct files in a directory into Veil management
veil add config/secrets

# make managed files appear in the current workspace
# also ensures the macOS TTL cleanup agent is installed
veil emerge

# make one managed file appear from any directory
veil emerge myapp:.env

# show lock, cleanup, authentication, and per-document timing
veil emerge --all --verbose

# edit the source document safely
veil edit .env

# inspect local materialized edits before committing them
veil diff .env

# inspect one materialized edit from any directory
veil diff myapp:.env

# commit materialized edits back to 1Password
veil commit .env

# commit a materialized edit from any directory
veil commit myapp:.env

# explicitly overwrite a remotely changed 1Password document after resolving a conflict
veil commit --overwrite-remote .env

# explicitly replace an edited materialized file with the 1Password document
veil emerge --overwrite-local myapp:.env

# remove materialized files from the workspace
veil vanish

# remove one materialized file from any directory
veil vanish myapp:.env

# remove materialized files from every registered workspace
veil vanish --all

# stop managing a target and keep it as a normal workspace file
veil remove .env

# stop managing a target from any directory
veil remove myapp:.env

# permanently delete a target from Veil and 1Password
veil purge --yes .env

# permanently delete a target from any directory
veil purge --yes myapp:.env

# stop managing the current workspace and keep its targets as normal files
veil workspace remove

# stop managing a named workspace from any directory (also accepts a missing root)
veil workspace remove myapp

# permanently delete the current workspace's targets from Veil and 1Password
veil workspace purge --yes

# manually repair or change the background cleanup interval
veil ttl-agent install --interval 60

veil emerge, veil commit, veil diff, veil remove, veil purge, and veil vanish accept workspace_id:target when they must address one registered file outside the current workspace. For example, myapp:.env and myapp:config/service-account.json identify two distinct targets in the same workspace. Within the active workspace, the shorter relative target path remains available.

With no target ref, veil emerge and veil vanish operate on every registered target in the active workspace. --all operates on every registered workspace and cannot be combined with a target ref.

TTL Cleanup

default_ttl controls how long a materialized file lease is valid. Expired clean files are removed by veil ttl-cleaner, and modified files are kept so local edits are not lost.

veil emerge fetches the current 1Password document and renews the lease expiration for every successfully materialized target, including targets that are already emerged.

veil status reports a modified file whose lease has expired as expired-modified. veil commit can safely commit that file using the last sync hash as its baseline and renews the lease after a successful remote conflict check. To discard the local changes instead, use veil emerge --overwrite-local workspace_id:target. The overwrite flag requires one target and cannot be combined with --all.

veil emerge --verbose writes state-lock wait time, TTL maintenance time, per-document 1Password read time, and total emerge time to standard error. In --all mode it also reports the separate 1Password authentication time. veil emerge --all downloads documents with up to eight concurrent workers.

Reviewing Materialized Edits

veil status shows a materialized target as modified when the workspace file no longer matches the last Veil sync hash. Use veil diff before committing the edit:

veil diff
veil diff .env
veil diff myapp:.env
veil diff --summary

veil diff compares the workspace file with the current 1Password document. If both sides changed since the last Veil sync, Veil reports a conflict. In that case, veil commit .env and veil vanish --commit refuse to overwrite 1Password implicitly. Review the diff, edit the workspace file to the desired final contents, then explicitly overwrite the remote document:

veil diff .env
veil commit --overwrite-remote .env
veil vanish

veil emerge automatically installs and loads the macOS LaunchAgent that runs TTL cleanup in the background. Manual agent commands are available for repair, inspection, and interval changes:

veil ttl-agent install --interval 60
veil ttl-agent status
veil ttl-agent uninstall

The LaunchAgent runs veil ttl-cleaner at the configured interval and once at load. If the Mac is asleep or powered off at the exact expiration time, cleanup happens on the next scheduled run after the machine is awake.

Configuration

Veil is designed around a single global config file:

version = 2
default_ttl = "24h"

[store]
backend = "1password_document"
vault = "Personal"

[workspaces.myapp]
root = "/Users/kaz/dev/myapp"
targets = [".env", "config/service-account.json"]

Each managed target has document metadata:

[[documents]]
workspace_id = "myapp"
target = ".env"
item_id = "op-item-id"
vault = "Personal"
title = "Veil: myapp: .env"

Development

Run the test suite:

go test ./...

Update the local ./veil binary from source:

go build -o veil ./cmd/veil

Scope

Veil is intentionally narrow in scope:

  • Personal use, not team secret management
  • File-level management, not key-level editing
  • Simple CLI workflow, not a large platform
  • Better separation and safer defaults, not a full security boundary

Status

This project is in early development.

License

Veil is licensed under the MIT License. See LICENSE for details.

About

A lightweight CLI for mounting secret files into your workspace only when needed.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages