Metadata-Version: 2.4
Name: movitera-cli
Version: 0.4.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: httpx<1,>=0.28.1
Requires-Dist: keyring<26,>=25
Requires-Dist: pyotp<3,>=2.9
Requires-Dist: rich<15,>=13
Requires-Dist: textual<9,>=0.60
Requires-Dist: typer<1,>=0.15
Description-Content-Type: text/markdown

# movitera CLI

Inject Movitera vault secrets as environment variables, browse credentials, 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" — no copy/paste).
#    Your team is auto-saved as the default.
movitera login

# 2. See what you can reach:
movitera whoami
movitera team list
movitera creds list

# 3. Run any command with secrets injected as env vars:
movitera run -c myapp-prod -- npm start

# 4. Or dump as dotenv (stdout, or a 0600 file with -o):
movitera secrets pull -c myapp-prod -o .env

# 5. Or generate a TOTP code:
movitera totp <credential-id>
```

Omit `-c`/`--credential` (or `--team`) on a terminal and the CLI shows an interactive picker.

## Interactive mode

Run `movitera` with no arguments on a terminal (or `movitera tui`) to open a
full-screen UI: a teams sidebar on the left, and on the right a search box over
your credentials **grouped by scope** (Privadas first, then each group, mirroring
the web app), filtering as you type. Keyboard-driven:

| Key | Action |
|---|---|
| `↑`/`↓` | Move between teams / credential rows |
| `/` | Jump to the search box (filters the current team's credentials) |
| `t` | Focus the teams list · `u` set the highlighted team as default |
| `Enter` | Open the action menu for the selected credential |
| `r` | Refresh · `q` quit |

Selecting an `ENV_BUNDLE` offers **copy to clipboard** or **write to a 0600
file**; other credentials offer a live **TOTP code** with a countdown. As in the
one-off commands, secret *values* are never rendered on screen.

This is purely additive — every one-off command below is unchanged, and a bare
`movitera` that isn't attached to a TTY (pipes, CI) prints help instead of
launching the UI, so scripts never block.

## 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` (and `secrets pull -o`
writes a `0600` file when you explicitly ask for one).

A single PAT works across every team you belong to: the token is minted against
one team but credential reads authorize by your team membership, so you can
`movitera team use <name>` to switch the default at any time.

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.
Non-secret preferences (default team, API URL) live in
`~/.config/movitera/config.json`.

## Config

Environment variables override the saved config file.

| 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 (overrides saved default) | — |
| `MOVITERA_CONFIG_DIR` | Base config dir (like `XDG_CONFIG_HOME`); the token + config live in `<dir>/movitera/` | `~/.config` |

Run `movitera config` to see the resolved paths and values.

## Commands

### `movitera` / `movitera tui`
Opens the interactive UI (see [Interactive mode](#interactive-mode)). On a
non-TTY, bare `movitera` prints help instead.

### `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), stores it in the OS keyring, and pins the approved team as
your default. The PAT never appears in the URL or browser history.

Headless escape hatches — 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> -c myapp-prod
```

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

### `movitera whoami`
Shows the API URL, auth source, default team, and a live connectivity check.

### `movitera team list` / `team use <name>` / `team show` / `team clear`
List the teams you belong to, pin a default (by name, slug, or id) so other
commands don't need `--team`, show the current default, or forget it.

### `movitera creds list [--team T] [--env] [--search Q]`
Browse credential metadata (names, kinds, tags) in a team. `--env` limits the
list to `ENV_BUNDLE` credentials; values are never shown.

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

### `movitera secrets pull [-c NAME] [--team T] [-o FILE]`
Writes the dotenv body to stdout, or to `FILE` (mode `0600`) with `-o`. Exits
non-zero on resolution failures so you can safely chain `... > .env`.

### `movitera totp [CREDENTIAL_ID] [--team T]`
Prints the current TOTP code for the credential's `OTPAUTH_URI` field. Omit the
id on a terminal to pick interactively.

### Shell completion
`movitera --install-completion` installs completion for your shell;
`movitera --show-completion` prints it.

> PAT management (creating/revoking tokens) lives in the Movitera web app — those
> endpoints require an interactive session, not a PAT.

## 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.
