# Env files

Share .env files with the people who can write a repository, end-to-end encrypted so Sailfork stores them without any key that can read them.

Env files are your repository's `.env`, `.env.local` or `apps/web/.env` files, shared with everyone who can write the
repository. Each file is encrypted on your machine before it is uploaded, to the devices your team approved. Sailfork
stores the encrypted file and never holds a key that can read it, so a breach of Sailfork, a leaked server key or
Sailfork going away exposes no value.

## Start

An owner of the organization (or you, for a personal repository) runs this once, in a clone:

```sh
sailfork env init --recovery-file ~/Documents/env-recovery.txt
```

Your device becomes the first admin. The recovery key decrypts everything and can approve devices if every admin device
is lost; keep it offline.

## Share and get files

```sh
sailfork env push          # every untracked .env file of the clone
sailfork env pull          # the team's latest, merged key by key with your edits
sailfork env status        # which files are in sync, edited or behind
```

`push` adds each file to `.gitignore` and refuses a file git already tracks, since its values are in the history.
Edits to different keys merge on their own. When you and the server changed the same key, `pull` stops and names it;
keep one side with `--theirs` or `--ours`.

`sailfork repo clone` brings the env files along once your device is approved.

## Add a device or a teammate

The first `sailfork env pull` on a new device asks to join and prints an approval code. An owner checks the code with
`sailfork env devices` and approves it:

```sh
sailfork env approve 7KQ2-M9XA
```

Matching codes prove both devices see the same list of devices. The approval re-encrypts the files for the new device.
To give a teammate whose device is approved this repository's files, run `sailfork env grant <handle>` in it.

## Remove someone

`sailfork env remove <handle>` (or a device id) re-encrypts every file without them in the same step. When someone
loses access on the web instead, the next owner command removes them; until then other devices refuse to push. Values
they already read stay with them: rotate those.

## Run without writing files

```sh
sailfork env run -- bun test
```

The command gets the values in its environment and nothing is written to disk, which suits agents and CI scripts on a
developer's machine. Agents see key names (`sailfork env keys`), never values.

## Keep a copy

`sailfork env export ./backup --identity` writes the encrypted files, their signed manifests and this device's key. The
standard [age](https://age-encryption.org) tool decrypts them without Sailfork:

```sh
age -d -i ./backup/identity.txt ./backup/.env.age > .env
```

## On the web

A repository's **Env files** page, for people who can write it, lists each file with its key names, versions and who
changed it, and a file's history shows which keys each version added or removed. The side column lists the owner's
devices, the devices waiting for approval with their codes and the exact `sailfork env approve` command, and anyone who
lost access but is still a recipient. The page never shows values and never approves anything itself: approving signs
with an admin's device.

## What Sailfork can and cannot see

Sailfork sees file paths, key names, versions and who changed what, so lists, merges and the history work. It cannot see
values. Every device checks the signed list of devices and each file's signed manifest, and refuses a file older than
one it has seen, so the server can neither add a device of its own nor bring back an old value.

CI/CD secrets are separate: they are set by admins and read only by jobs.

## Commands

## sailfork env

Share .env files with the people who can write the repository, end-to-end encrypted: the server cannot read them.

### sailfork env init

Start the owner's env device chain with this device as its admin, and make a recovery key to keep offline. Changes something.

```sh
sailfork env init [flags]
```

| Flag | What it does |
| --- | --- |
| `--recovery-file <PATH>` | Write the recovery key to this file (mode 0600) instead of printing it once. |

Examples:

```sh
sailfork env init --recovery-file ~/Documents/acme-env-recovery.txt
```

### sailfork env push

Encrypt and share env files; with no path, every untracked .env file of the clone and every one already shared. Changes something.

```sh
sailfork env push [PATHS...] [flags]
```

| Argument | What it is |
| --- | --- |
| `[PATHS...]` | Env files to push, relative to the current folder |

| Flag | What it does |
| --- | --- |
| `-m`, `--message <MESSAGE>` | A note for the file's history. |
| `--stdin <PATH>` | Read this file's content from stdin and write it to the clone first, e.g. from another secrets tool. |
| `--theirs` | Keep the server's value of a key both sides changed. |
| `--ours` | Keep this clone's value of a key both sides changed. |

Examples:

```sh
sailfork env push
sailfork env push .env apps/web/.env.local -m "rotate the Stripe test key"
```

### sailfork env pull

Decrypt the team's env files into this clone, merged key by key with local edits. Changes something.

```sh
sailfork env pull [PATHS...] [flags]
```

| Argument | What it is |
| --- | --- |
| `[PATHS...]` | Only these env files, relative to the current folder |

| Flag | What it does |
| --- | --- |
| `--theirs` | Keep the server's value of a key both sides changed. |
| `--ours` | Keep this clone's value of a key both sides changed. |

Examples:

```sh
sailfork env pull
sailfork env pull .env --theirs
```

### sailfork env status

Which env files match the server, have local edits or are behind. Read-only.

```sh
sailfork env status
```

Examples:

```sh
sailfork env status
```

### sailfork env keys

Key names of each env file and who changed it last, never values. Read-only.

```sh
sailfork env keys
```

Examples:

```sh
sailfork env keys --json
```

### sailfork env log

The versions of one env file: key names, author and message. Read-only.

```sh
sailfork env log [PATH]
```

| Argument | What it is |
| --- | --- |
| `[PATH]` | The env file |

Examples:

```sh
sailfork env log apps/web/.env.local
```

### sailfork env set

Set one key in an env file and push it. Changes something.

```sh
sailfork env set <ASSIGNMENT> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ASSIGNMENT>` | KEY=VALUE, or KEY=- to read the value from stdin so it stays out of shell history |

| Flag | What it does |
| --- | --- |
| `--file <FILE>` | The env file to change. Default `.env`. |
| `-m`, `--message <MESSAGE>` | A note for the file's history. |

Examples:

```sh
sailfork env set LOG_LEVEL=debug
```

### sailfork env unset

Remove one key from an env file and push it. Changes something.

```sh
sailfork env unset <KEY> [flags]
```

| Argument | What it is |
| --- | --- |
| `<KEY>` | The key to remove |

| Flag | What it does |
| --- | --- |
| `--file <FILE>` | The env file to change. Default `.env`. |
| `-m`, `--message <MESSAGE>` | A note for the file's history. |

Examples:

```sh
sailfork env unset OLD_FLAG
```

### sailfork env run

Run a command with the team's env values in its environment, writing nothing to disk. Changes something.

```sh
sailfork env run <COMMAND...> [flags]
```

| Argument | What it is |
| --- | --- |
| `<COMMAND...>` | The command and its arguments, after -- |

| Flag | What it does |
| --- | --- |
| `--file <PATH>` | Env files whose values to load, later ones winning (default: .env, then .env.local) Repeatable. |

Examples:

```sh
sailfork env run -- bun test
sailfork env run --file .env --file .env.test -- cargo test
```

### sailfork env devices

Devices in the owner's chain, devices waiting for approval with their codes, and people who lost access. Read-only.

```sh
sailfork env devices
```

Examples:

```sh
sailfork env devices
```

### sailfork env approve

Approve a waiting device whose code matches and re-encrypt its files for it (owners). Changes something.

```sh
sailfork env approve <CODE> [flags]
```

| Argument | What it is |
| --- | --- |
| `<CODE>` | The approval code the waiting device shows, such as 7KQ2-M9XA |

| Flag | What it does |
| --- | --- |
| `--recovery-file <PATH>` | Sign with the recovery key from this file instead of this device. |

Examples:

```sh
sailfork env approve 7KQ2-M9XA
```

### sailfork env grant

Let a person with an approved device read and write this repository's env files (owners). Changes something.

```sh
sailfork env grant <USER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<USER>` | The person's handle |

| Flag | What it does |
| --- | --- |
| `--recovery-file <PATH>` | Sign with the recovery key from this file instead of this device. |

Examples:

```sh
sailfork env grant alice
```

### sailfork env remove

Remove a person or one device from the chain and re-encrypt every file without them (owners). Changes something.

```sh
sailfork env remove <TARGET> [flags]
```

| Argument | What it is |
| --- | --- |
| `<TARGET>` | A person's handle, or a device id from `sailfork env devices` |

| Flag | What it does |
| --- | --- |
| `--recovery-file <PATH>` | Sign with the recovery key from this file instead of this device. |

Examples:

```sh
sailfork env remove alice
sailfork env remove 3f9a1c0d2b7e4a55
```

### sailfork env export

Write the encrypted files, their manifests and the chain to a folder the standard `age` tool reads. Changes something.

```sh
sailfork env export <DIR> [flags]
```

| Argument | What it is |
| --- | --- |
| `<DIR>` | Folder to write into |

| Flag | What it does |
| --- | --- |
| `--identity` | Also write this device's age identity to identity.txt (mode 0600) |

Examples:

```sh
sailfork env export ./env-backup --identity
```

---

Every docs page: https://sailfork.com/llms.txt
