---
title: "06 mdflow-crypt CLI"
canonical_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/805092df-0030-4567-ab01-3a4c7c06aff8
md_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/805092df-0030-4567-ab01-3a4c7c06aff8.md
visibility: public
---

# mdflow-crypt CLI

`mdflow-crypt` encrypts and decrypts MDflow documents **locally**, from the command line.

It is a standalone, zero-dependency CLI you run on your own machine. **Your plaintext and your password never leave your computer** — they never reach a server, and never reach an AI model.

Works on **Node 18 or later**. It does not need a Personal Access Token, and it is **not** Pro-gated — it operates on files, not on your account.

## Why it exists

MDflow encrypts a document's body in your browser (see [01 Document Encryption](/doc/b230e154-6c58-4bfd-8a7a-c70bc7bebcd7)), and the server only ever stores ciphertext (`mdflow-enc:v1:…`). That is a strong guarantee, but it has an awkward consequence: an encrypted document you exported is unreadable outside a browser that has the key.

This tool does the same crypto on your own machine, so you can take an encrypted document out of MDflow and read or write it offline.

## Usage

```bash
# decrypt: an mdflow-enc:v1 file → <name>_decrypted.md
npx mdflow-crypt decrypt notes.md

# encrypt: a markdown file → <name>_encrypted.md  (paste the result into MDflow)
npx mdflow-crypt encrypt notes.md
```

Install it permanently instead of using `npx`:

```bash
npm install -g mdflow-crypt
mdflow-crypt encrypt notes.md
```

The output is written next to the input, with the original extension dropped:

| Command | `report.md` becomes |
| --- | --- |
| `encrypt` | `report_encrypted.md` |
| `decrypt` | `report_decrypted.md` |

## Passwords

The password is resolved in this order — first match wins:

1. `--password <pw>` — an inline flag
2. `--password-file <path>` — read from a file (the first line)
3. the `[password]` positional argument
4. otherwise you are **prompted**, hidden (`encrypt` asks twice to confirm)

> **`--password` and the positional argument are visible to other processes and land in your shell history.** For anything sensitive, use the hidden prompt, or a `--password-file` with `chmod 600`.

```bash
# password from a file instead of the prompt
npx mdflow-crypt encrypt notes.md --password-file ~/.secrets/notes.pw
```

## Interoperability

The format is `mdflow-enc:v1` — PBKDF2 at 600,000 iterations, then AES-256-GCM. It is **the same format everywhere**:

- the web app,
- the iOS app ([02 iOS App](/doc/0a35e506-d632-4f07-aa6a-1d19a5ab3940)),
- the VS Code and Cursor extension ([01 VS Code and Cursor Extension](/doc/3baa2c9f-85cb-446d-b20e-1054cefee7c5)),
- this CLI.

Encrypt here, paste the ciphertext into MDflow, and it opens with the same password. Export an encrypted document from MDflow and decrypt it here. There is no lock-in, even for encrypted content.

## A warning about AI agents

This one matters:

> **Do not ask an AI agent to decrypt your documents.** The moment an agent runs `mdflow-crypt decrypt`, the plaintext is in its context — which is precisely the thing you encrypted the document to prevent.

`mdflow-crypt` is meant to be **run by a human**. The whole point of encrypting a document is that your agents cannot read it; handing an agent the password and the CLI dissolves that guarantee completely, and more quietly than you would like.

If you want an agent to work with the content, do not encrypt it. If you encrypted it, decrypt it yourself.

## Typical uses

- **Read an exported encrypted document** offline. A workspace export (see [02 Exporting a Workspace](/doc/7666542c-b167-4475-9026-2fb85f335e19)) contains encrypted documents as ciphertext — this is how you read them.
- **Recover content after cancelling Pro**, or after leaving MDflow entirely.
- **Prepare an encrypted document offline** and paste the ciphertext in.
- **Keep encrypted markdown in a git repository**, where only you can read it.

## If you lose the password

Nothing can be done. Not by this tool, not by MDflow, not by anyone. The key is derived from your password and exists nowhere else.