himitsu^秘密

Git-native secret sharing for teams that use Age, SOPS, Nix, and the terminal.

_{One secret per file • Path-based access control • Self-serve rekeys • TUI-first workflow • Output generation}

What is himitsu?

himitsu is an Age-based secrets manager built around a simple idea:

Your secret store should be a Git repo you can review, share, branch, sync, and recover.

Instead of hiding secrets behind a service, database, or cloud control plane, himitsu stores each secret as its own .age file inside a plain directory tree. Access is controlled by recipient files, organized by path. Team members can add recipients, rekey subtrees, review secret changes in Git, and run local commands with decrypted values injected into the environment.

It is designed for small teams, infrastructure repos, Nix/devShell workflows, and open-source projects that need something stronger than scattered .env files but lighter than Vault.

himitsu set prod/API_KEY "sk_live_..."
himitsu recipient add ops/alice --age-key age1...
himitsu rekey prod
himitsu exec prod/* -- node app.js

Why himitsu?

Most secret workflows become painful in one of two ways:

.env files and chat-based sharing are easy until they become impossible to audit, rotate, or trust.
Vault-style systems are powerful, but often too much machinery for small teams, local development, or Git-centered infrastructure.

himitsu sits in the middle. It keeps the operational model boring: encrypted files, Git history, Age recipients, and regular directories.

Use himitsu when you want:

Reviewable secret changes
One encrypted file per secret keeps diffs, renames, deletes, and reviews understandable.
Git-based collaboration
A store is just a Git repo, and supports multiple repos at once. Your own secrets stay separate without affecting your workflow.
Tag-based control
Organize recipients and secrets by directory, then rekey only the subtree that changed.
Fast local workflows
Use the TUI for browsing and editing, or the CLI for scripts, CI, and shell automation.
Generated outputs
Resolve named outputs: blocks into SOPS-encrypted YAML files for apps, CI, and deploy tooling.
Nix-friendly secret injection
Wrap devShells, packages, and entrypoints without introducing a long-running secrets service.

Quick Start

Run himitsu with no arguments to open the TUI. On a fresh machine, the init wizard creates your Age key, scaffolds a store, adds you as the first recipient, and drops you into search.

himitsu

From the dashboard you can search secrets, create new entries, edit values, copy references, switch stores, and check sync health.

For scripts and CI, use the CLI directly:

# Initialize a store
himitsu init --name you/secrets

# Store secrets
himitsu set prod/API_KEY "sk_live_abc123" --tag stripe --tag pci
himitsu set prod/DB_PASSWORD "correct-horse-battery-staple"

# Share access
himitsu recipient add ops/alice --age-key age1...
himitsu rekey prod

# Search and read
himitsu search stripe
himitsu get prod/API_KEY

# Run a command with prod secrets in the environment
himitsu exec prod/* -- node app.js

Stores can be local paths or remote Git repos:

himitsu remote add org/secrets
himitsu -r org/secrets set staging/API_KEY "sk_test_..."

Features
Install
Quick Start
TUI
Store Layout
Commands
- init
- set
- get
- read
- write
- ls
- rekey
- search
- tag
- exec
- recipient
- remote
- context
- migrate
- sync
- import
- export
- generate
- join
- ci
- git
- check
- keys
- doctor
- completions
- prime
- version
- docs
Self-Serve Rekeys
Global Options
Configuration
Sync & Store Health
Demo & Recordings
Nix Integration
Development
License

Intro

himitsu solves duplication and eases maintenance, and is made for the following workflow:

Create your personal store as a git repo e.g. user/secrets - personal secrets go here.
Any orgs/teams you are part of have a store at org/secrets - team secrets go here.
Access-control is path-based - configure who can access prod/* in .himitsu.yaml
Store secrets, organizing using plain directories, and tag them for crosscutting groupings (pci, mobile, rotate-2026-q1)
Map secrets to outputs by path or tag:

# .himitsu.yaml
...
outputs:
  web-service-{dev,staging,prod}:
    selectors:
      - common/*
      - $1/database-url
    aliases:
      SOME_VALUE: path/to/some-secret
      # Cross-store alias (another store via `github:org/repo#path`). Resolved
      # by `generate`; `exec` does not yet support cross-store secrets.
      SHARED_SECRET: github:org/secrets#prod/api-key

  pci-prod:
    selectors:
      - tag:pci+tag:prod
    aliases:
      STRIPE: tag:stripe

With this config you can run himitsu generate --target gen which will build SOPS-compatible yaml files to the gen/ directory, or himitsu exec <output-label> -- <cmd> to launch a process with the resolved secrets injected as environment variables. Note: exec resolves only local-store secrets; outputs whose aliases reference another store (github:org/repo#path) are supported by generate but not yet by exec.

Migrating from `envs:` to `outputs:`

Existing stores: run himitsu migrate envs once. See migration guide.

Features

Age-only encryption -- no KMS, no GPG, no SOPS. One .age file per secret.
One file per secret -- .himitsu/secrets/<path>.age keeps diffs readable.
Path-based recipients -- organize keys into directories (e.g. ops/alice, team/*); re-encrypt for all with rekey.
Generated outputs -- generate SOPS-encrypted YAML files from outputs: definitions in project config.
Cross-store search -- himitsu search reads every known store directly; results are live, no index to rebuild.
Tags -- attach free-form labels to secrets (pci, stripe, rotate-2026-q1); filter with --tag on set, search, ls, and exec, or compose outputs with tag:foo entries.
Run with secrets -- himitsu exec <ref> -- <cmd> resolves an output label, glob, or single secret and launches a process with the values injected as environment variables.
TUI -- in-terminal dashboard with fuzzy search, secret viewer, inline editing, and store health.
Import / Export -- bulk import from 1Password (op) or SOPS files; export as SOPS-encrypted YAML/JSON.
Nix integration -- flake library for devShell injection, secret packaging, and container entrypoints.

Install

# Nix (run directly)
nix run github:darkmatter/himitsu -- <command>

# Nix (add to a devShell)
{
  inputs.himitsu.url = "github:darkmatter/himitsu";
  # ...
  devShells.default = pkgs.mkShell {
    packages = [ himitsu.packages.${system}.default ];
  };
}

# Build from source
cargo build --release

Quick Start

The fastest path is the TUI. Run himitsu with no subcommand: if no age key exists yet, the init wizard launches automatically and walks you through scaffolding a store. Once that completes you land on the search dashboard.

himitsu          # opens the TUI (init wizard on first run, dashboard otherwise)

From the dashboard you can fuzzy-search secrets, ctrl-n to create one, ctrl-p for the command palette, enter to view, e to edit -- see TUI for the full keymap.

CLI / scripting

The same operations are available as scriptable subcommands. Use these in CI, shell scripts, or when you'd rather stay in your editor:

# Initialize headlessly (skip the wizard)
himitsu init --name you/secrets

# Store and read secrets
himitsu set prod/API_KEY     "sk_live_abc123" --tag pci --tag stripe
himitsu set prod/DB_PASSWORD "hunter2"
himitsu set dev/DB_PASSWORD  "devpass" --no-push   # batch-friendly
himitsu get prod/API_KEY                            # -> sk_live_abc123

# List, rekey, search
himitsu ls                  # -> dev/, prod/
himitsu ls prod             # -> API_KEY, DB_PASSWORD
himitsu ls --tag pci        # AND-filter by tag (drops undecryptable entries)
himitsu rekey               # re-encrypt for current recipient set
himitsu search DB           # cross-store fuzzy search
himitsu search "" --tag pci # all secrets carrying tag `pci`

# Run a command with secrets in its environment
himitsu exec prod/* -- node app.js                     # inject every prod secret
himitsu exec pci-prod --tag rotate -- ./run-checks.sh  # output label + tag filter

Override the active store with -s (path) or -r (slug):

himitsu -s /path/to/.himitsu set prod/API_KEY "sk_live_xxx"
himitsu -r org/repo get prod/API_KEY

TUI

Launch the interactive terminal UI:

himitsu        # no subcommand opens the TUI

Search is the root view -- the app opens straight into a fuzzy filter over every secret in the active store. Start typing to narrow the list, arrow keys to move, enter to open. Press ? in any view for a help overlay, or ctrl-p to open the command palette -- the canonical, fuzzy-filterable list of every action the current view exposes.

Search (root)

Key	Action
type	filter results
`up` / `down`	move selection
`enter`	open selected secret
`backspace`	delete filter char
`ctrl-p`	command palette
`ctrl-n`	new secret
`ctrl-s`	switch store
`ctrl-y`	copy selected value
`Y` (`shift-y`)	copy `himitsu read <ref>` for the selected row
`shift-e`	browse output presets
`?`	help
`esc` / `ctrl-c`	quit

Secret viewer

Key	Action
`r`	reveal / hide value
`y`	copy decrypted value to clipboard
`Y` (`shift-y`)	copy `himitsu read <ref>` (the command, not the value)
`e`	edit in `$EDITOR`
`R`	rekey for current recipients
`d`	delete (confirms with `y`)
`?`	help
`esc`	back

Y lets you share how to fetch a secret in a PR comment, chat message, or runbook without putting the plaintext on your clipboard. The clipboard gets himitsu read prod/API_KEY (or himitsu -r org/repo read … when the row lives in a different store from the active one), ready to paste into a terminal that has the right age key.

New-secret form

Fields: path, value, description, tags, url, totp, env_key, expires_at. The tags field accepts a comma-separated list (e.g. pci, stripe, rotate-2026-q1); only [A-Za-z0-9_.-,] is accepted at typing time, and each tag is validated against the grammar on submit.

Key	Action
`tab` / `enter`	next field
`shift-tab`	previous field
`ctrl-s` / `ctrl-w`	save
`esc` / `ctrl-c`	cancel

The secret viewer renders tags as accent-colored chips alongside the description and other metadata, and search rows show the same chips inline next to the description column.

Store Layout

.himitsu/
  secrets/
    prod/
      API_KEY.age
      DB_PASSWORD.age
    dev/
      DB_PASSWORD.age
  recipients/
    self.pub                   # your key (added on init)
    ops/
      alice.pub                # path-based: ops/alice
      deploy-bot.pub           # path-based: ops/deploy-bot
  config.yaml                  # store-level config
  schemas/
    secrets.json

The keyring lives separately:

~/.local/share/himitsu/        # $XDG_DATA_HOME/himitsu
  key                          # age private key
  key.pub                      # age public key

~/.local/state/himitsu/        # $XDG_STATE_HOME/himitsu
  stores/<org>/<repo>/         # managed remote store checkouts

Commands

`himitsu init`

Create an age keypair and scaffold the store. Adds self.pub as a recipient automatically.

himitsu init                              # interactive TUI wizard
himitsu init --name you/secrets           # headless, creates/restores a primary store
himitsu init --name org/repo --url <url>  # restore from a custom git remote

`himitsu set <path> <value>`

Encrypt and store a secret. Path is slash-delimited (prod/API_KEY).

himitsu set prod/API_KEY "sk_live_abc123"
himitsu set dev/DB_PASSWORD "devpass" --no-push
himitsu set prod/STRIPE_KEY "sk_live_..." --tag pci --tag stripe

Optional flags:

Flag	Purpose
`--description <text>`	Human-readable description, surfaced in `search` and the TUI viewer.
`--url <url>`	Associated dashboard URL.
`--totp <otpauth-or-base32>`	TOTP secret (URI or raw base32 ≥ 16 chars).
`--env-key <NAME>`	Default env-var name when this secret is injected via `exec` (else derived from the path tail).
`--expires-at <when>`	RFC 3339 timestamp, relative duration (`30d`, `6mo`, `1y`), or `never`.
`--tag <T>`	Attach a tag. Repeatable. Grammar: `[A-Za-z0-9_.-]+`, 1-64 chars, case-sensitive.

`himitsu get <path>`

Decrypt and print a secret for humans.

himitsu get prod/API_KEY

`himitsu read <path>`

Print a secret's plaintext bytes to stdout with no decoration. Use this in scripts where extra formatting would be unsafe or annoying.

himitsu read prod/API_KEY
himitsu read github:org/repo/prod/API_KEY

`himitsu write <path> [value]`

Write a secret's plaintext from an argument or stdin. Like set, this encrypts before writing and can attach tags.

himitsu write prod/API_KEY "sk_live_abc123"
printf '%s' "$TOKEN" | himitsu write prod/API_KEY --stdin --tag pci --tag stripe
himitsu write dev/DB_PASSWORD "devpass" --no-push

`himitsu ls [prefix]`

Browse secrets like a directory. Pass --tag to filter to secrets carrying the listed tag(s); the filter decrypts each candidate to read its tags, so entries the current identity can't decrypt are dropped (we can't verify their tags). Plain himitsu ls never touches the identity.

himitsu ls                # -> dev/, prod/
himitsu ls prod           # -> API_KEY, DB_PASSWORD
himitsu ls --tag pci      # AND across multiple --tag flags
himitsu ls prod --tag pci --tag rotate-2026-q1

`himitsu rekey [prefix]`

Re-encrypt secrets for the current recipient set. Run after adding or removing recipients.

himitsu rekey         # everything
himitsu rekey prod    # one subtree

`himitsu search <query>`

Fuzzy-search secret paths across every known store. Results are read live from store files on every invocation -- there is no SQLite index to rebuild, and decrypted descriptions and tags are pulled best-effort with the ambient age key.

himitsu search DB                 # fuzzy across all stores
himitsu search "" --tag pci       # empty query + tag = "all PCI secrets"
himitsu search stripe --tag pci   # fuzzy AND tag-filtered
himitsu search DB --refresh       # accepted as a no-op; kept for backward compat

--tag is repeatable with AND-semantics. Secrets the current identity can't decrypt are excluded when any --tag is set, since their tags can't be verified.

`himitsu tag <path> add|rm|list`

Add, remove, or list tags on a single secret. Mutates by decrypt → edit tags → re-encrypt → write, preserving every other field.

himitsu tag prod/STRIPE_KEY add pci stripe rotate-2026-q1
himitsu tag prod/STRIPE_KEY list           # -> pci\nrotate-2026-q1\nstripe
himitsu tag prod/STRIPE_KEY rm rotate-2026-q1

add is idempotent (existing tags don't duplicate); rm is a no-op for absent tags. The grammar [A-Za-z0-9_.-]+ (1-64 chars, case-sensitive) is validated up front for both add and rm.

`himitsu exec <REF> -- <CMD>...`

Run a command with secrets injected as environment variables. <REF> is one of:

Output label from project config outputs: (e.g. pci-prod) -- uses the output's alias key (or path-derived key) as the variable name. Resolves local-store secrets only.
Path glob ending in /* (e.g. prod/*).
Concrete secret path (e.g. prod/API_KEY).
Tag selector (e.g. tag:pci+tag:prod).

Cross-store / provider-qualified refs (e.g. github:org/repo/prod/API_KEY) are not yet supported by exec and return a clear error -- run from the owning store with -r <org/repo> exec <local-ref>. Output (outputs:) entries that reference a cross-store secret are likewise not yet supported by exec.

himitsu exec pci-prod -- node app.js
himitsu exec tag:pci+tag:prod -- node app.js
himitsu exec prod/*+tag:pci -- ./run-checks.sh
himitsu exec prod/API_KEY -i -- env | grep API_KEY    # `-i` = clean env

The variable name for each secret comes from (in priority order): the output alias key → SecretValue.env_key → derive_env_key(path tail) (e.g. api-key → API_KEY, group/item-name → GROUP__ITEM_NAME). Two secrets resolving to the same env-var name is a hard error naming both source paths.

If a selector matches no secrets, himitsu exec exits 1 with error: selector 'X' matched no secrets.

--clean / -i starts the child with an empty environment plus only PATH, HOME, and TERM. The child's exit code is propagated; signal termination reports 128 + signum on Unix.

`himitsu recipient add|rm|ls|show`

Manage recipients with path-based names. Slash-separated paths create a directory hierarchy (e.g. ops/alice -> recipients/ops/alice.pub).

himitsu recipient add laptop --self
himitsu recipient add ops/alice --age-key "age1abc..." --description "Alice"
himitsu recipient show ops/alice
himitsu recipient rm ops/alice
himitsu recipient ls

`himitsu remote add|remove|list|default`

Manage remote store registrations.

himitsu remote add org/repo                           # clone from GitHub
himitsu remote add git@github.com:org/repo.git        # full URL also works
himitsu remote add org/repo --url https://custom/url   # custom git host
himitsu remote default org/repo                        # set default store
himitsu remote list
himitsu remote remove org/repo

`himitsu context remote|clear`

Set or clear the active store context used to disambiguate bare secret paths when multiple stores are configured.

himitsu context
himitsu context remote org/secrets
himitsu context remote github:org/secrets
himitsu context clear

`himitsu migrate envs`

Migrate legacy environment-based stores to outputs: and tags.

himitsu migrate envs --dry-run
himitsu migrate envs

The migration folds legacy secret environment fields into tags, rewrites legacy envs: config blocks to outputs:, removes the old env-cache file, and writes a config backup before changing project YAML.

`himitsu sync [store]`

Pull from the git remote and optionally rekey drifted secrets.

himitsu sync          # all stores
himitsu sync org/repo # one store

See Sync & Store Health for the auto-commit / auto-push behavior, --no-push, and the auto_pull config switch.

`himitsu import`

Import secrets from 1Password (--op) or a SOPS-encrypted file (--sops). Both backends shell out to external tools, so they must be on PATH:

1Password -- requires the op CLI, signed in to the relevant account.
SOPS -- requires sops; decryption runs as sops -d <file>.

himitsu import prod/STRIPE_KEY --op "op://Engineering/Stripe/api_key"
himitsu import prod          --op "op://Engineering/Stripe"   # whole item
himitsu import prod          --sops secrets.enc.yaml --dry-run

`himitsu export`

Export secrets matching a glob as a SOPS-encrypted file. Requires sops on PATH; encryption is piped through sops --encrypt so plaintext never hits disk.

himitsu export "prod/*" -o prod.sops.yaml

`himitsu generate`

Generate SOPS-encrypted output files from outputs: definitions in project config. Also requires sops on PATH -- same pipe-through-stdin contract as export. Pass --stdout to print plaintext YAML instead of writing encrypted files.

himitsu generate           # all outputs defined in himitsu.yaml
himitsu generate --output prod
himitsu generate --output prod --stdout

Note: the --env flag has been removed; use --output to specify which output to generate.

`himitsu join`

Join a store by adding your own age public key to its recipient list. If your key is not already a recipient, this adds it, commits, and pushes the change so other members can rekey the store for you.

himitsu join
himitsu join --name my-laptop

`himitsu ci`

Manage the GitHub Actions workflow for self-serve rekeys.

himitsu ci install --default-remote org/repo
himitsu ci status
himitsu ci run --operation add-recipient --recipient-name ops/alice

`himitsu git [args...]`

Run any git command inside the store directory.

himitsu git status
himitsu git log --oneline
himitsu git --all status       # all stores

`himitsu check [store]`

Verify that known store checkouts are up to date with their remotes. Exits non-zero when a checked store is behind its remote tracking branch.

himitsu check
himitsu check org/repo --offline

`himitsu keys public|private`

Print age keys for yourself or a named recipient.

himitsu keys                 # own public key
himitsu keys public          # own public key
himitsu keys public ops/alice
himitsu keys private self

`himitsu doctor`

Audit the active store's recipients, encrypted secret recipient lists, and configured key provider.

himitsu doctor
himitsu -r org/repo doctor

`himitsu completions [shell]`

Generate shell completion scripts. Completion scripts include dynamic secret path completion for path-oriented commands.

himitsu completions bash
himitsu completions zsh
himitsu completions fish
himitsu completions --refresh-cache

`himitsu prime`

Print an AGENTS.md snippet that teaches coding agents how to use himitsu in the current repository.

himitsu prime >> AGENTS.md

`himitsu version`

Print version information.

himitsu version

`himitsu docs`

Render this README in the terminal.

himitsu docs

Self-Serve Rekeys

himitsu allows teams to manage secret access via GitHub Actions. When a new team member needs access to a store, they don't have to wait for an operator to manually rekey secrets for them. Instead, they can request access, and GitHub Actions handles the rekeying automatically.

To configure self-serve rekeys:

Install the workflow into your repository:
```
himitsu ci install --default-remote org/repo
```
This creates a .github/workflows/himitsu.yml file.
Ensure your GitHub repository has a HIMITSU_AGE_KEY secret configured with an age private key that has read/write access to the store.

Edit the generated .github/workflows/himitsu.yml to write the key to disk before the darkmatter/himitsu action runs:

 steps:
   - uses: actions/checkout@v4
   - name: Setup age key
     run: |
       mkdir -p ~/.local/share/himitsu
       echo "${{ secrets.HIMITSU_AGE_KEY }}" > ~/.local/share/himitsu/key
   - uses: darkmatter/himitsu@main

Commit and push the workflow:

himitsu git add .github/workflows/himitsu.yml
himitsu git commit -m "chore: add himitsu self-serve rekey workflow"
himitsu git push

When a user wants to request access, they can run himitsu join to add their public key to the repository. Once their key is merged, the GitHub Action can be triggered manually via gh workflow run himitsu.yml --field operation=sync or automatically via your own triggers to pull the new recipient and rekey the secrets.

Global Options

Flag	Description
`--project[=<path>]`	Use project context. Bare `--project` resolves the nearest git repository from `cwd`; `--project=<path>` uses the repo at that path. Requires a project config (`.himitsu/config.yaml` or `himitsu.yaml`) inside the repo. Without this flag, store-touching commands ignore project config and use the global default.
`-r, --remote <slug>`	Select a store by `org/repo` slug (or full git URL).
`-v, --verbose`	Increase log verbosity (`-v` debug, `-vv` trace).
`-s, --store <path>`	Hidden / advanced: override the store path directly. Prefer `--project` for repo-scoped workflows and `--remote` for explicit slugs.

Configuration

User-level settings live at ~/.config/himitsu/config.yaml. Every field has a HIMITSU_<FIELD> environment override (uppercased, dots become underscores) that takes precedence over the file.

# Default store when neither -s nor -r is given.
default_store: myorg/secrets        # env: HIMITSU_DEFAULT_STORE

# Where the age private key lives:
#   "disk"           — `<data_dir>/key` (the default).
#   "macos-keychain" — macOS Keychain entry under
#                      `io.darkmatter.himitsu.agekey.byfp.v1`. Switching
#                      to keychain on an already-initialized machine
#                      auto-migrates the on-disk secret into the keychain
#                      and removes `<data_dir>/key`. The pubkey file
#                      always stays on disk for fingerprint discovery.
key_provider: disk                  # env: HIMITSU_KEY_PROVIDER

# When true, every store-touching command first runs `git fetch` and
# fast-forwards before dispatching, so reads see latest state and writes
# can't fast-fail on a remote-side commit. Failures are non-fatal.
auto_pull: false                    # env: HIMITSU_AUTO_PULL

tui:
  # Built-in palette. `random` (the default) picks one per launch.
  # Accepted: random, himitsu, apathy, apathy-minted, apathy-theory,
  #           apathy-storm, ayu, catppuccin, material, rose-pine.
  theme: random                     # env: HIMITSU_TUI_THEME

  # Opt in to Nerd Font glyphs in the dashboard. Off by default because
  # there is no reliable runtime check for font support.
  nerd_fonts: false

  # Per-action keybindings. Each action takes a list, so multiple keys can
  # trigger the same action. Unspecified actions fall back to the
  # hardcoded defaults documented in [TUI](#tui). Leader-key chords are
  # whitespace-separated (see "Leader-key chords" below).
  keys:
    new_secret:  ["F2", "ctrl+n"]
    save_secret: ["ctrl+x s"]
    quit:        ["esc", "ctrl+q"]

Binding strings are <mod>+<mod>+<code>, lowercased, modifiers first -- e.g. "ctrl+n", "shift+tab", "esc", "?", "F2". Uppercase characters imply shift ("Y" == "shift+y"). Bare letters match case-insensitively, so "y" matches both y and Y. Malformed bindings surface as a clear config error at startup.

Leader-key chords

Multi-step chord bindings are written as whitespace-separated steps:

tui:
  keys:
    # Press Ctrl+X, then s. Useful when terminal/tmux ate Ctrl+S (XOFF).
    save_secret: ["ctrl+x s"]
    # Mix and match — multiple bindings per action; chord and single-step
    # entries can coexist.
    new_secret:  ["F2", "ctrl+x ctrl+n"]

When you press the first step of a chord, the dashboard shows a ctrl+x … breadcrumb at the bottom of the screen and waits for the continuation. A non-continuation key aborts the chord (no spurious action fires; the breadcrumb flips to chord aborted: …). Single-step bindings still flow through each view's normal key handling, so you can keep typing into the search box without your letters getting eaten.

There is no chord timeout — the dispatcher resolves on the next key, not on a wall clock. If you bind both ctrl+x (single-step) and ctrl+x s (chord) to different actions, the chord wins: pressing ctrl+x enters the pending state instead of firing the single-step binding immediately.

The full action list (with defaults) is in rust/src/tui/keymap.rs: quit, help, command_palette, new_secret, switch_store, copy_selected, copy_ref_selected, envs, reveal, copy_value, copy_ref, rekey, edit, delete, back, save_secret, next_field, prev_field, cancel.

Sync & Store Health

Himitsu treats the store as an append-only git repo and keeps git status clean for you.

Auto-commit on every mutation. set, write, rekey, import, recipient add/rm, etc. each produce a commit (himitsu: <action>) on success or himitsu: FAILED: <action>: <error> on failure -- the working tree is never left dirty.
Auto-push on success. When the commit lands and a remote is configured, himitsu also runs git push. Pass --no-push on set, write, or import to skip the push (handy for batch loads); the next mutation without --no-push will flush everything.
Auto-pull (opt-in). Set auto_pull: true (or HIMITSU_AUTO_PULL=1) to fetch and fast-forward before every store-touching command. Failures surface as a stderr warning rather than aborting the command.

The TUI dashboard renders a store-health indicator in the header bar with the following states:

State	Meaning
`synced`	Local checkout matches the remote tracking branch.
`behind N`	Tracking branch is ahead of local by N commits -- run `himitsu sync`.
`dirty`	Working tree has uncommitted changes (rare; usually a manual edit).
`behind+dirty`	Both behind remote AND has local changes.
`no remote`	Repo exists but no remote -- run `himitsu remote add <slug>`.
`not pushed`	Remote configured, tracking branch missing -- run `himitsu git push -u origin main`.
`not git`	Store directory is not a git repo (init bug, almost never happens).
`unknown`	Status couldn't be determined; treat as a hint to investigate.

Demo & Recordings

The headline demo at the top of this README is demo/demo-vhs.gif, rendered from demo/demo.tape. The smaller demo/tui-us-*.{tape,gif,cast} files are per-user-story regression / demo artifacts -- one per shipped TUI story (US-008 new-secret form, US-011 browse, US-012 viewer, etc.) -- and double as visual tests that the documented flow still works.

To regenerate locally:

cargo build --release
vhs demo/demo.tape                 # canonical headline GIF
vhs demo/tui-us-011.tape           # one specific story

CI re-renders every tape on changes to demo/**, rust/**, or the workflow file (.github/workflows/vhs.yml). The CI run redirects each tape's Output line to a scratch path under target/vhs-out/ so the checkout never picks up binary diffs; the rendered GIFs are uploaded as a build artifact (vhs-demo-renders) for inspection. Commit a refreshed demo-vhs.gif only when you intend the README hero to change.

Nix Integration

The Nix helper library currently exposes the older env-oriented packing API (env, mergeEnvs, and .himitsu/vars/<env>). The CLI's current project output model is outputs:; use himitsu generate for new SOPS output files and the Nix helpers for existing devShell / entrypoint integration.

{
  inputs.himitsu.url = "github:darkmatter/himitsu";

  outputs = { self, nixpkgs, himitsu, ... }: let
    system = "x86_64-linux";
    lib = himitsu.lib.${system};
  in {
    devShells.default = lib.mkDevShell {
      devShell = pkgs.mkShell { packages = [ nodejs ]; };
      store    = ./.himitsu;
      env      = "dev";
    };

    packages.my-secrets = lib.packSecrets ./.himitsu/vars/prod;
  };
}

Output	Description
`packages.default`	The `himitsu` CLI binary.
`packages.age-key-cmd`	Prints the local age private key (useful as `SOPS_AGE_KEY_CMD`).
`lib.mkDevShell`	Wrap a devShell with automatic secret decryption.
`lib.packSecrets`	Collect `.age` files into a Nix derivation.
`lib.wrapAge`	`age` pre-configured with the local identity.
`lib.wrapSops`	`sops` pre-configured to discover the himitsu key.
`lib.mkEntrypoint`	Container entrypoint that decrypts then execs.

Development

nix develop                    # enter dev shell
cargo build                    # debug build
cargo build --release          # release build
cargo test --workspace         # all tests
cargo fmt --all -- --check     # format check
cargo clippy --workspace --all-targets -- -D warnings

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 253 Commits
.agents/skills		.agents/skills
.beads		.beads
.codex		.codex
.github/workflows		.github/workflows
.himitsu		.himitsu
action		action
demo		demo
docs		docs
nix/lib		nix/lib
proto		proto
rust/src		rust/src
screenshots		screenshots
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTEXT.md		CONTEXT.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md
action.yml		action.yml
bacon.toml		bacon.toml
build.rs		build.rs
flake.lock		flake.lock
flake.nix		flake.nix
justfile		justfile
package.json		package.json
skills-lock.json		skills-lock.json

Folders and files

Latest commit

History

Repository files navigation

himitsu秘密

What is himitsu?

Why himitsu?

Quick Start

Table of Contents

Intro

Migrating from envs: to outputs:

Features

Install

Quick Start

CLI / scripting

TUI

Search (root)

Secret viewer

New-secret form

Store Layout

Commands

himitsu init

himitsu set <path> <value>

himitsu get <path>

himitsu read <path>

himitsu write <path> [value]

himitsu ls [prefix]

himitsu rekey [prefix]

himitsu search <query>

himitsu tag <path> add|rm|list

himitsu exec <REF> -- <CMD>...

himitsu recipient add|rm|ls|show

himitsu remote add|remove|list|default

himitsu context remote|clear

himitsu migrate envs

himitsu sync [store]

himitsu import

himitsu export

himitsu generate

himitsu join

himitsu ci

himitsu git [args...]

himitsu check [store]

himitsu keys public|private

himitsu doctor

himitsu completions [shell]

himitsu prime

himitsu version

himitsu docs

Self-Serve Rekeys

Global Options

Configuration

Leader-key chords

Sync & Store Health

Demo & Recordings

Nix Integration

Development

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

himitsu^秘密

Migrating from `envs:` to `outputs:`

`himitsu init`

`himitsu set <path> <value>`

`himitsu get <path>`

`himitsu read <path>`

`himitsu write <path> [value]`

`himitsu ls [prefix]`

`himitsu rekey [prefix]`

`himitsu search <query>`

`himitsu tag <path> add|rm|list`

`himitsu exec <REF> -- <CMD>...`

`himitsu recipient add|rm|ls|show`

`himitsu remote add|remove|list|default`

`himitsu context remote|clear`

`himitsu migrate envs`

`himitsu sync [store]`

`himitsu import`

`himitsu export`

`himitsu generate`

`himitsu join`

`himitsu ci`

`himitsu git [args...]`

`himitsu check [store]`

`himitsu keys public|private`

`himitsu doctor`

`himitsu completions [shell]`

`himitsu prime`

`himitsu version`

`himitsu docs`

Packages