Metadata-Version: 2.4
Name: movitera-cli
Version: 0.2.0
Summary: Movitera CLI: inject vault secrets as environment variables, generate TOTP codes
Project-URL: Homepage, https://github.com/joaoheusi/movitera-cli
Project-URL: Repository, https://github.com/joaoheusi/movitera-cli
Project-URL: Issues, https://github.com/joaoheusi/movitera-cli/issues
Author: Movitera
License-Expression: MIT
License-File: LICENSE
Keywords: cli,dotenv,movitera,password-manager,secrets,totp,vault
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: <4,>=3.11
Requires-Dist: click<9,>=8.1
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: keyring<26,>=25
Requires-Dist: pyotp<3,>=2.9
Description-Content-Type: text/markdown

# movitera CLI

Inject Movitera vault secrets as environment variables, render dotenv files, and generate TOTP codes from the terminal. Authenticates with a Movitera vault personal access token (PAT).

## Install

```bash
pip install movitera-cli
# or install as an isolated CLI tool (recommended):
pipx install movitera-cli
# or with uv:
uv tool install movitera-cli
# or run without installing:
uvx --from movitera-cli movitera --help
```

## Quick start

```bash
# 1. Sign in (opens your browser, click "Authorize", done — no copy/paste):
movitera login

# 2. Run any command with secrets injected as env vars:
movitera run --team <teamId> --credential myapp-prod -- npm start

# 3. Or dump as dotenv:
movitera secrets pull --team <teamId> --credential myapp-prod > .env

# 4. Or generate a TOTP code for a credential:
movitera totp --team <teamId> <credential-id>
```

## How it works

`movitera run -- cmd` fetches the dotenv body from
`GET /vault/credentials/by-name/{name}/env`, then `exec`s the child process
with those vars merged into its environment. The CLI never writes secrets
to disk — they exist only in the child process's `environ`.

Tokens are stored in the OS keyring (Keychain on macOS, libsecret on Linux,
Credential Manager on Windows) with a file fallback under
`~/.config/movitera/token` (mode `0o600`) if no keyring backend is
available.

## Config

| Env var | Purpose | Default |
|---|---|---|
| `MOVITERA_API_URL` | API base URL | `https://api.movitera.com` |
| `MOVITERA_TOKEN` | PAT override (skips keyring lookup) | — |
| `MOVITERA_TEAM` | Default team id (you can omit `--team`) | — |

## Commands

### `movitera login`
Opens your default browser to the Movitera approval screen. Click
"Authorize" and the CLI captures a freshly minted PAT via a one-time
grant code (PKCE-protected), then stores it in the OS keyring. The PAT
itself never appears in the URL or browser history.

Headless escape hatches — preserved for CI, SSH, and Docker where no
browser is available:

```bash
# Paste a PAT directly:
movitera login --token mvt_pat_…

# Pipe a PAT from another tool (`pass`, `vault`, etc.):
pass show movitera/pat | movitera login --stdin

# Or skip `login` entirely by setting MOVITERA_TOKEN at runtime:
export MOVITERA_TOKEN=mvt_pat_…
movitera secrets pull --team <teamId> --credential myapp-prod
```

### `movitera logout`
Removes the stored PAT.

### `movitera run --team T --credential N -- <cmd> [args...]`
Fetches the `ENV_BUNDLE` credential named `N` and execs `<cmd>` with those
vars in the environment.

### `movitera secrets pull --team T --credential N`
Writes the dotenv body to stdout. Exits non-zero on resolution failures so
you can chain `movitera secrets pull ... > .env`.

### `movitera totp --team T <credential-id>`
Prints the current TOTP code for the credential's `OTPAUTH_URI` field.

### `movitera tokens list --team T` / `movitera tokens revoke <id>`
Manage your own PATs from the CLI.

## Security model

- PATs have full 256-bit entropy and are stored as SHA-256 on the server,
  so a server compromise cannot recover the plaintext.
- Every `movitera run` invocation is audited server-side, but PAT reads
  are **coalesced per hour per token** (see the backend's
  `FETCHED_VIA_TOKEN` aggregation) so a hot dev loop doesn't drown the log.
- Group/team access is re-checked on every request: if your vault scope is
  revoked, your PAT immediately loses access — no token-cache divergence.
