Metadata-Version: 2.5
Name: noldorian
Version: 0.2.6
Summary: Local 0600 credential vault and operator CLIs
Project-URL: Documentation, https://pypi.org/project/noldorian/
Project-URL: Homepage, https://pypi.org/project/noldorian/
Author: Everplay-Tech LLC
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,credentials,mcp,secrets,security,vault
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Noldorian

Install the current public release with no version pin:

```bash
python3 -m pip install noldorian
# or
pipx install noldorian
# or
uv tool install noldorian
```

Then run `noldorian doctor`. The JSON field `version` is what is installed.

This package is a local 0600 vault plus operator CLIs. It is not a
background service. This wheel has no Unix-socket server, LaunchAgent,
daemon, or root-owned installer.

Noldorian keeps API tokens out of chat, argv, and logs. A human pastes a
secret once into a 0600 vault. A child process gets the environment and does
the work. Agents can discover the install and the vault contract; they never
receive secret values.

## Commands

Six console scripts. `noldorian <name> …` also dispatches to the family CLIs
(`xabra`, `xadabra`, `xalakazam`, `abra` / `binabra`).

### noldorian

| Command | What it does |
|---------|----------------|
| `noldorian doctor` | JSON: install, vault path, name list, whether PyPI has a newer version. Does not install. |
| `noldorian upgrade --confirm` | Download the current package from `https://pypi.org/simple`. Vault file is not replaced. Without `--confirm`, prints the receipt only. |
| `noldorian run --env-file PATH -- cmd …` | Same as `xabra run`. |
| `noldorian env …` / `noldorian copy …` | Same as `xabra env` / `xabra copy`. |

`--version` prints the installed version.

### xabra — vault

The first `noldorian` or `xabra` command creates `~/.config/noldorian/` (0700)
and an empty `vault.env` (0600). Agents must not mkdir that directory. Values
never print.

```bash
xabra env set TOKEN_NAME
xabra run --env-file ~/.config/noldorian/vault.env -- your-command
```

| Command | What it does |
|---------|----------------|
| `xabra env set NAME` | Hidden prompt; store `NAME=value` in the vault. |
| `xabra env set-file NAME /path` | Store `NAME__FILE=/path` (file contents loaded at run time). |
| `xabra env init` | Create an empty 0600 vault file if missing. |
| `xabra env list` | Names only. |
| `xabra env probe NAME` | JSON: present / non-empty / mode. No secret value. |
| `xabra run --env-file PATH -- cmd …` | Load the vault into the child environment and run `cmd`. |
| `xabra run --env NAME -- cmd …` | Prompt for `NAME` (not stored) and run `cmd`. |
| `xabra copy NAME` | Copy the vault value to the clipboard without printing it. Default TTL 45s (`--ttl 0` disables). `--env-line` copies `NAME=value`. |
| `xabra macos-keychain unlock --env NAME --file VAULT` | Unlock a macOS keychain in-process from a vault name. Optional `--keychain PATH` and `--probe-identity HASH`. Password never goes on argv. |

Vault lines: `NAME=value`, `NAME__FILE=/path`, `NAME__CMD=cmd`. The file must
be mode 0600.

A leftover `~/.config/keyabra/keyabra.env` is not the live Noldorian vault.
If that file still exists, `noldorian doctor` refuses to create an empty
canonical vault on top of it. Backup and remove the leftover, then rerun
`noldorian doctor` so the package can create `~/.config/noldorian` itself.

### xabra — verified install

Optional. Default registry is empty: `~/.config/noldorian/apps.json`. Until
you add entries, `--list` reports nothing to install.

| Command | What it does |
|---------|----------------|
| `xabra --list` | Apps in the operator registry and whether they are installed. |
| `xabra --app NAME --status` | Installed vs resolved source. |
| `xabra --app NAME --install [--dmg PATH] [--yes]` | Fetch, verify, install. `--yes` skips the confirm prompt. |
| `xabra --app NAME --update` | Install only if a newer source resolves. |
| `xabra --update --all` | Same, every registry app. |
| `xabra --app NAME --update --protocol` | Repoint that app's MCP enrollment at the installed binary. |
| `xabra --app NAME --open` | Open an installed GUI app, or print the CLI path. |
| `xabra --doctor` | Vault / install / local tools (`hdiutil`, `gh`, …). |

`--json` prints a receipt.

### xadabra — paste-once runner

Runs a shell block with `{{placeholders}}`. Default source is the clipboard;
pass a file path or `-` for stdin. It prints a preview, then asks `Run?`
unless `--yes`. Secrets used as placeholders are masked in the preview.

| Flag | What it does |
|------|----------------|
| `--dry-run` | Preview only; do not execute. |
| `--yes` / `-y` | Skip the Run? prompt. |
| `--cloud` | No clipboard or interactive prompts. Values come from `--set NAME=value` or `XADABRA_NAME` env. Blocks `snx` unless `--allow-spells`. |
| `--set NAME=value` | Repeatable placeholder fill. |
| `--allow-spells` | Cloud only: allow `snx` in the script. |

`xadabra noldorian guide` prints the pip install walkthrough.
`xadabra noldorian install` prints `pip install noldorian==<this version>`.
`xadabra noldorian script` prints pip + doctor + `xabra env set NAME`.

### xalakazam — orienter

Callable memory. Prints how to install and use Noldorian on this machine.

| Command | What it does |
|---------|----------------|
| `xalakazam --deploy` | Install, vault, MCP, PATH (same facts as this README). |
| `xalakazam --bootstrap` | Short pip / uv install lines, then `noldorian doctor`. |
| `xalakazam --spells` | Noldorian is not a spellbook; pip is the install path. |
| `xalakazam --owner-actions` | Owner-only UI / purchase / secret checkpoint rite. |
| `xalakazam --enable` | `xabra copy NOLDORIAN_TOKEN` onto the clipboard (5 min TTL). |
| `xalakazam --setup-script` | Print a `pip install noldorian` snippet. |
| `xalakazam --all` | deploy + spells + owner-actions. |

### abra — bin-directory anchor

`abra` is the CLI. The Python import is `binabra` from this wheel. The
PyPI project named `abra` is a different, unrelated package. Do not
install a second distribution for this CLI.

```bash
source "$(abra sh)"
```

| Command | What it does |
|---------|----------------|
| `abra sh` | Path to bundled `anchor.sh`. |
| `abra embed` | Print `source "$(abra sh)"`. |
| `abra dir` | Discover bin (`ABRA_BIN`, project `bin/`, `~/.local/bin`). |
| `abra exec TOOL args` | Run a sibling from the discovered bin. |
| `abra init [dir]` | Create `bin/abra` in a project. |
| `abra colocate [dest]` | Copy `abra` into an existing bin folder. |

Python: `from binabra import anchor_dir, sibling, discover_bin`.

### noldorian-mcp — stdio MCP

```bash
noldorian-mcp
# equivalent: python3 -m noldorian.mcp
```

Point an MCP client at that executable from the pip/pipx install. Call
`doctor` first. Tools never return credential values.

| Tool | What it returns |
|------|-----------------|
| `doctor` | Same facts as `noldorian doctor`. |
| `orient` | How to install and use Noldorian (`topic`: `deploy`, `bootstrap`, `owner-actions`, `all`). |
| `list_vault_names` | Names only. Empty if no vault. |
| `child_run_template` | The owner-run command template. Does not execute. |

## Upgrade

`noldorian doctor` reports whether PyPI has a newer version. It does not
install it. Upgrade is an explicit download:

```bash
pipx upgrade noldorian
# or
noldorian upgrade --confirm
```

That replaces the package only. `~/.config/noldorian/vault.env` is not inside
the install, so names stay. There is no background auto-update.

Maintainers upload to PyPI with `twine`. GitHub releases do not upload the
package.

## Python

```python
from noldorian.vault import load_env_file, run_with_env
```

## License

Apache License 2.0. Report security issues privately to the maintainers; do
not open a public issue that contains secrets.
