Edit Secrets: Capy TUI vs. Editing .env Directly

There are two equally valid ways to change a secret in Capy. They land at the same place — encrypted ciphertext in .env and on the service — but they fit different moments.

Option 1 — `capy edit` (interactive TUI)

capy edit opens a two-pane inspector for the current project and branch:

  capy edit: my-app (development)

  development         12 tracked              2 drift              0 conflicts
  active branch       shown as abc…xyz snip… changed local/remote all clear

  Variables                                              │  DATABASE_URL
  KEY              VALUE        STATUS         UPDATED   │
> DATABASE_URL     pos…dev      * local        local     │  status   * local
  API_KEY          sk_…wxy      * in sync      in sync   │  updated  local
  STRIPE_KEY       sk_…abc      * remote       remote    │
  …                                                      │  value
                                                         │  pos…dev

  ↑↓ navigate · r reveal · e edit · c commit & push (1) · q quit

Reveal with r — values display as abc…xyz snippets by default; pressing r shows the full value of the selected row only.
Edit with e — type the new value, Enter to buffer, Esc to cancel.
Commit with c — encrypts, updates keep.lock, pushes to the service, and writes back to .env in one step.
Quit with q — if you have uncommitted edits, you’ll be prompted to commit & push, discard, or keep working.

Reach for this when you want to:

See what’s currently set without opening your editor.
Rotate one value with no risk of pasting plaintext into the wrong line.
Avoid running a separate capy step to encrypt and push.

Full keybindings and statuses live on the capy edit reference page.

Option 2 — Edit `.env` directly

You can also just open .env in your editor, replace any capy:… snippet (or add a new line) with plaintext, save, and run capy:

- DATABASE_URL=capy:abc123:eyJ2IjoxLCJ...
+ DATABASE_URL=postgres://user:pw@db.prod.example.com:5432/app
  API_KEY=capy:def456:eyJ2IjoxLCJ...
+ NEW_FLAG=true

capy

capy picks up that DATABASE_URL and NEW_FLAG are now plaintext, encrypts them with the project key, updates keep.lock, and rewrites the file with capy:… snippets again. Plaintext values disappear from .env automatically on the next sync — they don’t linger on disk. Reach for this when you want to:

Add a brand-new variable.
Rotate several values at once alongside code changes.
Stay in the editor you already have open.

If your edit conflicts with what’s on the service (a teammate also rotated the same key), capy opens the conflict resolver so you can pick a side. See Syncing secrets.

Which one should I use?

There’s no wrong answer — they encrypt the same way and land at the same place. A rough split:

You want to…	Reach for
Skim or rotate a single existing value	`capy edit`
Add a brand-new variable	edit `.env`, then `capy`
Change values alongside code in your editor	edit `.env`, then `capy`
Avoid plaintext in your editor’s undo history	`capy edit`
Resolve a conflict between local and remote	`capy` (conflict resolver)

What ends up on disk

In both flows:

.env always carries capy:{resourceId}:{ciphertext} snippets after the operation completes — never plaintext.
keep.lock advances to a new pinned hash for the branch.
The service receives the new ciphertext and the updated manifest.
A local cache of the encrypted blob is updated so capy run works offline.

Getting started

Using Capy

Deploying

Organizations

Branches

Team

CLI reference

Under the hood

Comparisons

Edit Secrets: Capy TUI vs. Editing .env Directly

Option 1 — `capy edit` (interactive TUI)

Option 2 — Edit `.env` directly

Which one should I use?

What ends up on disk

What’s next

capy edit (CLI reference)

Syncing secrets

​Option 1 — capy edit (interactive TUI)

​Option 2 — Edit .env directly

​Which one should I use?

​What ends up on disk

​What’s next

capy edit (CLI reference)

Syncing secrets

Option 1 — `capy edit` (interactive TUI)

Option 2 — Edit `.env` directly

Which one should I use?

What ends up on disk

What’s next