Metadata-Version: 2.5
Name: qwik-envr
Version: 0.5.1
Summary: A local browser editor for Unix shell environment variables.
Project-URL: Homepage, https://github.com/Qwik-Tools/envr
Project-URL: Repository, https://github.com/Qwik-Tools/envr
Project-URL: Issues, https://github.com/Qwik-Tools/envr/issues
Author: Himakar Reddy
License-Expression: MIT
License-File: LICENSE
Keywords: cli,environment,secrets,shell,unix
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: BSD
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# envr

Edit shell environment variables in your browser. Run `envr`, and it opens a local
table for the `export NAME=value` entries in a marked section of your startup file.
Add, edit, save, or delete entries without dumping the rest of your shell config.

**Package:** `qwik-envr` on PyPI · **Command:** `envr` · **Python:** 3.9+

## Install

```sh
pipx install qwik-envr
# or use a virtual environment
python3 -m venv .venv
. .venv/bin/activate
python -m pip install qwik-envr
```

The unrelated PyPI package named `envr` is **not** this project. Do not install both
in the same environment: they may share the `envr` import/command name.

## Quick start

Run `envr`. If your config has no markers, it asks permission once:

```text
Allow envr to create and manage a secrets block in ~/.zshrc? [y/N]
```

Answer **yes** to append an empty marker pair and open the editor; **no**, Enter,
or Ctrl-D leaves the file untouched. Future runs recognize the pair and do not
ask again. Existing settings are preserved. You can also add the two **identical**
marker lines yourself:

```sh
##</env secrets>
export API_KEY='your-value'
export DATABASE_URL='postgres://localhost/example'
##</env secrets>
```

Then run:

```console
$ envr
envr: macOS 26.3 (arm64) -- OK
envr: 2 exports from ~/.zshrc at http://127.0.0.1:49152/<random-token>/
envr: Ctrl-C to stop
```

The port and access token are randomly assigned each run. Your default browser
opens automatically; the server stays running until **Ctrl-C**. Each row has
**Save** and **Delete** buttons; use **Add** for new variables. Changes save
immediately. Refresh the page to reload changes made in another editor.

If the startup file is missing, an interactive run asks before creating an empty,
owner-only file (`0600`, subject to umask). It then separately asks permission to
initialize the managed block. Marker creation uses the same syntax validation,
conflict detection and atomic writes as normal saves, but does **not** source the
file. Noninteractive runs, `--json` and `-q` never prompt or initialize a block.
If exactly one marker exists, envr reports the incomplete pair rather than
guessing where your secrets end. Existing files are never replaced with an empty
config just to create a new block.

## Platform and shell support

The platform gate accepts desktop/server Unix-like systems, including macOS,
Linux, the BSDs, Solaris, and AIX. Local verification is on macOS, including
sh/bash integration. Other Unix platforms are not independently verified.
Windows, mobile Python, and browser/WASI runtimes are not supported.

`$SHELL` selects the default **file to edit**:

| Shell | Default file |
| --- | --- |
| zsh | `$ZDOTDIR/.zshrc` if set, otherwise `~/.zshrc` |
| bash | `~/.bashrc` |
| ksh | `~/.kshrc` |
| sh, dash, ash | `~/.profile` |

If `$SHELL` is unset or unsupported, envr chooses the first existing file among
`~/.zshrc`, `~/.bashrc`, and `~/.profile`, falling back to `~/.profile`.
`--file PATH` overrides this selection. Known filenames select their matching
validation shell; custom filenames use the supported `$SHELL`, or `sh`.
The selected shell must be installed to save changes.

These are editing defaults, not a guarantee of what every shell startup mode
loads. Bash login shells may use `.bash_profile`; ksh may require `ENV` to point
to `.kshrc`. Use `--file` for your setup. Fish/csh syntax is not supported.

## Commands

| Command | Behavior |
| --- | --- |
| `envr` | Open the local editor in your default browser |
| `envr --file ~/.bash_profile` | Edit a specific file |
| `envr --no-browser` | Print the URL without opening a browser |
| `envr --timeout 120` | Stop after 120 seconds; default `0` means until Ctrl-C |
| `envr --json` | Print one JSON document with platform/config metadata and variable names, **not values**; no prompts/server |
| `envr -q` | Unix platform gate only; silent, no config file access |
| `envr --mac -q` | macOS-only gate; silent, no config file access |
| `envr --version` | Print the version |
| `python -m envr` | Same command when using the installed interpreter |

Exit codes: `0` = supported platform, `1` = unsupported platform (or server startup
failure), `2` = invalid usage, `130` = interrupted. Config/marker problems are
reported but do not change the platform verdict. `--mac` exits `1` off macOS.

## Editing rules and safe saves

- The **first two** marker lines delimit the block. Put them at top level, not
  inside quoted strings, functions, conditionals, or here-documents.
- Editable entries are single-line literal `export NAME=value` statements.
  Plain, single-quoted, double-quoted, and escaped literal values are supported.
- Names use `[A-Za-z_][A-Za-z0-9_]*` (at most 128 characters); values are at most
  4096 characters, without newline, NUL, or invalid Unicode. Duplicate names are
  rejected when adding or editing.
- Comments and blank lines are preserved. If a block contains shell expressions
  such as `$HOME`, command substitution, multiline values, or other statements,
  the **whole block is read-only**. Edit those blocks manually. Nothing is evaluated
  merely to display the table.
- Edited values are treated as **literal strings**, safely shell-quoted. Untouched
  entries, inline comments, line endings, and content outside the block stay intact.
- Existing symlinks are followed; the target is updated without replacing the link.
  The target's Unix permission bits are retained. Atomic replacement changes the
  inode; hard-link relationships, ACLs, and extended attributes are not preserved.
- External changes are detected before replacement and rejected. Refresh before
  retrying. Use one editor tab/session per file; this is not a multiuser editor.

On save, envr writes a private temporary candidate in the same directory, runs
`<shell> -n` against it, and replaces the live file **only if validation succeeds**.
If validation fails or the shell is unavailable, the original file is unchanged.
Temporary files are removed afterward.

### Sourcing: important limitation

After saving, envr executes `. <file>` in a **child shell** with a 15-second timeout.
Raw shell output is discarded so secrets cannot leak into HTTP errors or terminal
logs; the page reports whether sourcing completed successfully.

**This executes your entire startup file, including commands outside the block.**
Use envr only with configurations you trust. Syntax validation is not a sandbox.
Startup guards may skip parts of a file in a noninteractive child shell.

A child process cannot change an already-open terminal's environment. To apply
changes there, run the appropriate command yourself:

```sh
source ~/.zshrc     # zsh
source ~/.bashrc    # bash
. ~/.profile       # POSIX sh
```

## Security

The server binds **127.0.0.1 only**, uses an OS-assigned port and a random 192-bit
token in the URL, and rejects foreign Host/Origin headers. It has no external
assets, analytics, CORS permissions, or runtime package dependencies. Responses
use `no-store`, `no-referrer`, `nosniff`, frame denial, and a nonce-based script CSP.
JSON writes are bounded and validated; displayed values are not inserted as HTML.

The local URL grants **read/write access** and sourcing permission: do not share
it. It can remain in browser history and terminal scrollback. This is a local
convenience tool, not encrypted secret storage or a sandbox against other processes
running as your user. Close the server when finished. See [SECURITY.md](SECURITY.md).

## Development

```sh
git clone https://github.com/Qwik-Tools/envr.git
cd envr
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e . --group dev
python -m pytest
ruff check src tests
ruff format --check src tests
mypy src/envr
python -m build
python -m twine check dist/*
```

Tests use temporary config files; they do not edit or source your real startup file.
Each test has a timeout to prevent accidental indefinite server runs.

```text
src/envr/system.py       platform detection
src/envr/shellrc.py      config selection, read/create prompt
src/envr/secretblock.py  marker extraction helper
src/envr/secretfile.py   literal parsing, CRUD, validated writes, child sourcing
src/envr/webview.py      loopback HTTP API and browser table
src/envr/cli.py          command-line entry point
```

The distribution is `qwik-envr`; Python imports remain under `envr`. The main
library interface is `SecretStore.load(path, shell=...)`, then `items()`,
`add()`, `update()`, `delete()`, `save()`, and `reload()`. `StoreError.code` is
stable; error details never include values. Store access must be serialized by
the caller (the HTTP server does this). Maintained by Qwik-Tools / Himakar Reddy.

## License

[MIT](LICENSE).
