vw-cli 0.2.0__py3-none-any.whl

vw_cli/__init__.py

@@ -0,0 +1,12 @@
+from .error import VwError
+from .crypto import VwCryptoKey, derive_master_key, _safe_int, decode_encrypted, aes_cbc_decrypt, decrypt_bytes, decrypt, HAS_ARGON2
+from .auth import VwAuth, REQUEST_TIMEOUT
+from .vault import VwVault
+from .cli import VERSION, USAGE, main
+
+__all__ = [
+    "VwError", "VwCryptoKey", "VwAuth", "VwVault",
+    "derive_master_key", "_safe_int", "decode_encrypted", "aes_cbc_decrypt",
+    "decrypt_bytes", "decrypt", "HAS_ARGON2",
+    "REQUEST_TIMEOUT", "VERSION", "USAGE", "main",
+]

vw_cli/__main__.py

@@ -0,0 +1,3 @@
+from vw_cli.cli import main
+
+main()

vw_cli/auth.py

@@ -0,0 +1,123 @@
+import json
+import os
+import time
+import uuid
+
+import requests
+
+from .error import VwError
+
+REQUEST_TIMEOUT = 30
+TOKEN_CACHE_DIR = os.path.expanduser("~/.config/vw-cli")
+TOKEN_CACHE_PATH = os.path.join(TOKEN_CACHE_DIR, "token.json")
+TOKEN_CACHE_TTL = 3600
+TOKEN_CACHE_ENV = "VW_CLI_TOKEN_CACHE"
+
+
+def _token_cache_path() -> str:
+    return os.environ.get(TOKEN_CACHE_ENV, TOKEN_CACHE_PATH)
+
+
+class VwAuth:
+    def __init__(self, identity_url: str, client_id: str, client_secret: str):
+        self.identity_url = identity_url.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._session = requests.Session()
+        self._token: str | None = None
+        self._server_url: str | None = None
+        self._load_token()
+
+    def _http(self, method: str, url: str, **kw) -> dict:
+        kw.setdefault("timeout", REQUEST_TIMEOUT)
+        r = self._session.request(method, url, **kw)
+        if r.status_code != 200:
+            raise VwError(f"{method} {url} → {r.status_code}: {r.text[:300]}")
+        return r.json()
+
+    def _cache_key(self) -> str:
+        return f"{self.identity_url}|{self.client_id}"
+
+    def _load_token(self):
+        path = _token_cache_path()
+        try:
+            with open(path) as f:
+                data = json.load(f)
+            if data.get("key") == self._cache_key():
+                age = time.time() - data.get("saved_at", 0)
+                if age < TOKEN_CACHE_TTL:
+                    self._token = data.get("access_token")
+                    self._server_url = data.get("server_url")
+                    if self._token:
+                        self._session.headers.update(
+                            {"Authorization": f"Bearer {self._token}"}
+                        )
+        except (FileNotFoundError, json.JSONDecodeError, KeyError):
+            pass
+
+    def _save_token(self):
+        path = _token_cache_path()
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w") as f:
+            json.dump({
+                "key": self._cache_key(),
+                "access_token": self._token,
+                "server_url": self._server_url,
+                "saved_at": time.time(),
+            }, f)
+
+    def clear_cache(self):
+        try:
+            os.remove(_token_cache_path())
+        except FileNotFoundError:
+            pass
+
+    def login(self):
+        if self._token:
+            return
+
+        if not self.client_id or not self.client_secret:
+            raise VwError("VW_CLIENTID and VW_CLIENTSECRET must be set")
+
+        for attempt in range(3):
+            try:
+                r = self._http(
+                    "POST", f"{self.identity_url}/connect/token",
+                    data={"grant_type": "client_credentials",
+                          "client_id": self.client_id,
+                          "client_secret": self.client_secret,
+                          "scope": "api",
+                          "device_identifier": str(uuid.uuid4()),
+                          "device_type": "2",
+                          "device_name": "vw-cli"},
+                    headers={"Content-Type": "application/x-www-form-urlencoded"})
+            except VwError as e:
+                if "429" in str(e) and attempt < 2:
+                    wait = 10 * (attempt + 1)
+                    print(f"rate limited – retrying in {wait}s ...",
+                          file=__import__("sys").stderr)
+                    time.sleep(wait)
+                    continue
+                raise
+
+            tok = r.get("access_token")
+            if not tok:
+                raise VwError("login failed – no access_token in response")
+            self._token = tok
+            self._session.headers.update(
+                {"Authorization": f"Bearer {self._token}"}
+            )
+            self._save_token()
+            return
+
+    def request(self, method: str, url: str, **kw) -> dict:
+        for attempt in range(2):
+            try:
+                return self._http(method, url, **kw)
+            except VwError as e:
+                if "401" in str(e) and attempt == 0:
+                    self._token = None
+                    self.clear_cache()
+                    self.login()
+                    continue
+                raise

vw_cli/cli.py

@@ -0,0 +1,123 @@
+import os
+import sys
+import json
+from urllib.parse import urlparse
+
+import requests
+
+from .error import VwError
+from .auth import VwAuth
+from .vault import VwVault
+
+VERSION = "0.2.0"
+
+USAGE = """\
+usage: vw-cli <command> [args]
+
+commands:
+  login                     authenticate with API key
+  sync                      sync vault and print raw JSON
+  unlock                    unlock vault (derive encryption key)
+  list                      list all item names
+  get password <item>       print password for <item>
+  get item <item>           print full decrypted <item> as JSON
+
+environment:
+  VW_SERVER          vault server URL (default: https://vault.bitwarden.com)
+  VW_CLIENTID        API client ID  (user.xxxx)
+  VW_CLIENTSECRET    API client secret
+  VW_PASSWORD        master password
+"""
+
+
+def _setup_urls(server_url: str) -> tuple[str, str]:
+    host = urlparse(server_url).hostname or ""
+    if "bitwarden" in host:
+        identity_url = "https://identity.bitwarden.com"
+        api_url = "https://api.bitwarden.com"
+    else:
+        base = server_url.rstrip("/")
+        identity_url = f"{base}/identity"
+        api_url = base
+    return identity_url, api_url
+
+
+def main():
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print(USAGE, end="")
+        sys.exit(0)
+    if sys.argv[1] in ("--version",):
+        print(f"vw-cli {VERSION}")
+        sys.exit(0)
+
+    cmd = sys.argv[1]
+
+    server_url = os.environ.get("VW_SERVER", "https://vault.bitwarden.com")
+    identity_url, api_url = _setup_urls(server_url)
+    client_id = os.environ.get("VW_CLIENTID", "")
+    client_secret = os.environ.get("VW_CLIENTSECRET", "")
+    password = os.environ.get("VW_PASSWORD", "")
+
+    try:
+        if cmd == "login":
+            auth = VwAuth(identity_url, client_id, client_secret)
+            auth.login()
+            print("ok – logged in")
+
+        elif cmd == "sync":
+            auth = VwAuth(identity_url, client_id, client_secret)
+            auth.login()
+            vault = VwVault(api_url, password, auth.request)
+            data = vault.sync()
+            print(json.dumps(data, indent=2))
+
+        elif cmd == "unlock":
+            auth = VwAuth(identity_url, client_id, client_secret)
+            auth.login()
+            vault = VwVault(api_url, password, auth.request)
+            vault.sync()
+            vault.unlock()
+            print("ok – vault unlocked")
+
+        elif cmd == "list":
+            auth = VwAuth(identity_url, client_id, client_secret)
+            auth.login()
+            vault = VwVault(api_url, password, auth.request)
+            vault.sync()
+            vault.unlock()
+            for name in vault.list_names():
+                print(name)
+
+        elif cmd == "get":
+            if len(sys.argv) < 4:
+                print("usage: vw-cli get password|item <name>\n", file=sys.stderr)
+                sys.exit(1)
+            sub = sys.argv[2]
+            name = sys.argv[3]
+            auth = VwAuth(identity_url, client_id, client_secret)
+            auth.login()
+            vault = VwVault(api_url, password, auth.request)
+            vault.sync()
+            vault.unlock()
+            if sub == "password":
+                print(vault.get_password(name))
+            elif sub == "item":
+                print(json.dumps(vault.get_item(name), indent=2))
+            else:
+                print(f"unknown sub-command: get {sub}", file=sys.stderr)
+                sys.exit(1)
+
+        else:
+            print(f"unknown command: {cmd}\n{USAGE}", file=sys.stderr)
+            sys.exit(1)
+
+    except VwError as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except requests.RequestException as e:
+        print(f"network error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

vw_cli/crypto.py

@@ -0,0 +1,112 @@
+import hashlib
+import hmac
+import base64
+from dataclasses import dataclass
+from typing import Optional
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+try:
+    from argon2.low_level import hash_secret_raw, Type
+    HAS_ARGON2 = True
+except ImportError:
+    HAS_ARGON2 = False
+
+from .error import VwError
+
+
+@dataclass
+class VwCryptoKey:
+    enc: bytes
+    mac: bytes
+
+
+def derive_master_key(
+    password: str, email: str, kdf: int, iterations: int,
+    memory: int = 64, parallelism: int = 4,
+) -> tuple[bytes, bytes]:
+    salt = email.lower().encode("utf-8")
+    pw = password.encode("utf-8")
+
+    if kdf == 0:
+        mk = hashlib.pbkdf2_hmac("sha256", pw, salt, iterations, 32)
+    elif kdf == 1:
+        if not HAS_ARGON2:
+            raise VwError("Argon2id KDF requires argon2-cffi.  "
+                          "Install: pip install argon2-cffi")
+        mk = hash_secret_raw(secret=pw, salt=salt,
+                             time_cost=iterations,
+                             memory_cost=memory * 1024,
+                             parallelism=parallelism, hash_len=32,
+                             type=Type.ID, version=19)
+    else:
+        raise VwError(f"unsupported KDF type {kdf}")
+
+    hsh = hashlib.pbkdf2_hmac("sha256", mk, pw, 1, 32)
+    return mk, hsh
+
+
+def _safe_int(v, default: int) -> int:
+    if isinstance(v, int):
+        return v
+    if isinstance(v, str):
+        try:
+            return int(v)
+        except ValueError:
+            return default
+    return default
+
+
+def decode_encrypted(enc_str: str) -> tuple[Optional[bytes], Optional[bytes], Optional[bytes]]:
+    if not enc_str:
+        return None, None, None
+
+    parts = enc_str.split(".")
+
+    # Format: type.iv|ct|mac  (e.g. "2.iv|ct|mac")
+    if len(parts) == 2:
+        rest = parts[1]
+        sub = rest.split("|")
+        if len(sub) == 3:
+            return (base64.b64decode(sub[0]),  # iv
+                    base64.b64decode(sub[2]),  # mac
+                    base64.b64decode(sub[1]))  # ct
+
+    # Format: iv.mac.ct
+    if len(parts) == 3:
+        return (base64.b64decode(parts[0]),
+                base64.b64decode(parts[1]),
+                base64.b64decode(parts[2]))
+
+    # Combined format: single base64 blob (iv(16) + mac(32) + ct)
+    raw = base64.b64decode(parts[0])
+    if len(raw) < 48:
+        return None, None, None
+    return raw[:16], raw[16:48], raw[48:]
+
+
+def stretch_key(mk: bytes, info: str) -> bytes:
+    return hmac.new(mk, info.encode() + b"\x01", hashlib.sha256).digest()
+
+
+def aes_cbc_decrypt(ct: bytes, key: bytes, iv: bytes) -> bytes:
+    c = Cipher(algorithms.AES(key), modes.CBC(iv))
+    d = c.decryptor()
+    padded = d.update(ct) + d.finalize()
+    pad = padded[-1]
+    return padded[:-pad]
+
+
+def decrypt_bytes(enc_str: str, k: VwCryptoKey) -> bytes:
+    iv, mac, ct = decode_encrypted(enc_str)
+    if iv is None:
+        return b""
+    if mac:
+        want = hmac.new(k.mac, iv + ct, hashlib.sha256).digest()
+        if not hmac.compare_digest(want, mac):
+            raise VwError("HMAC mismatch – wrong password or corrupted data")
+    return aes_cbc_decrypt(ct, k.enc, iv)
+
+
+def decrypt(enc_str: str, k: VwCryptoKey) -> str:
+    return decrypt_bytes(enc_str, k).decode("utf-8")

vw_cli/error.py

@@ -0,0 +1,2 @@
+class VwError(Exception):
+    pass

vw_cli/vault.py

@@ -0,0 +1,175 @@
+from typing import Callable, Optional
+
+import base64
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding as asym_padding
+
+from .error import VwError
+from .crypto import VwCryptoKey, decrypt, decrypt_bytes, derive_master_key, stretch_key, _safe_int
+
+
+class VwVault:
+    def __init__(self, api_url: str, password: str, http_func: Callable):
+        self.api_url = api_url.rstrip("/")
+        self.password = password
+        self._http = http_func
+        self._profile: Optional[dict] = None
+        self._ciphers: list[dict] = []
+        self._crypto_key: Optional[VwCryptoKey] = None
+        self._org_keys: dict[str, VwCryptoKey] = {}
+        self._name_cache: Optional[dict[str, dict]] = None
+
+    # ------------------------------------------------------------------
+    # sync
+    # ------------------------------------------------------------------
+    def sync(self) -> dict:
+        self._profile = {}
+        self._ciphers = []
+        self._name_cache = None
+        data = self._http("GET", f"{self.api_url}/api/sync")
+        self._profile = data.get("profile", {})
+        self._ciphers = data.get("ciphers", [])
+        return data
+
+    # ------------------------------------------------------------------
+    # unlock
+    # ------------------------------------------------------------------
+    def unlock(self):
+        if not self.password:
+            raise VwError("VW_PASSWORD must be set")
+        if not self._profile:
+            self.sync()
+
+        p = self._profile
+        email = p.get("email", "")
+        if not email:
+            raise VwError("email missing from profile – cannot derive key")
+        kdf = _safe_int(p.get("kdf"), 0)
+        iterations = _safe_int(p.get("kdfIterations"), 600000)
+        memory = _safe_int(p.get("kdfMemory"), 64)
+        parallelism = _safe_int(p.get("kdfParallelism"), 4)
+
+        enc_key = p.get("key") or p.get("encryptedKey")
+        if not enc_key:
+            raise VwError("no encrypted key in profile – "
+                          "make sure you are using a user API key (user.xxxx)")
+
+        mk, _h = derive_master_key(self.password, email, kdf,
+                                    iterations, memory, parallelism)
+        uk = decrypt_bytes(enc_key,
+                           VwCryptoKey(enc=stretch_key(mk, "enc"),
+                                       mac=stretch_key(mk, "mac")))
+        if len(uk) != 64:
+            raise VwError(f"expected 64-byte symmetric key, got {len(uk)}")
+        self._crypto_key = VwCryptoKey(enc=uk[:32], mac=uk[32:])
+
+        # Decrypt RSA private key
+        priv_enc = p.get("privateKey")
+        if priv_enc:
+            priv_raw = decrypt_bytes(priv_enc, self._crypto_key)
+            priv_key = serialization.load_der_private_key(priv_raw, password=None)
+
+            # Decrypt organization keys
+            for org in p.get("organizations", []):
+                org_id = org.get("id")
+                org_key_enc = org.get("key")
+                if not org_id or not org_key_enc:
+                    continue
+                enc_type = org_key_enc.split(".")[0]
+                if enc_type == "4":
+                    org_cipher = base64.b64decode(org_key_enc.split(".", 1)[1])
+                    org_dec = priv_key.decrypt(
+                        org_cipher,
+                        asym_padding.OAEP(
+                            mgf=asym_padding.MGF1(algorithm=hashes.SHA1()),
+                            algorithm=hashes.SHA1(),
+                            label=None,
+                        ),
+                    )
+                    org_key = VwCryptoKey(enc=org_dec[:32], mac=org_dec[32:])
+                    self._org_keys[org_id] = org_key
+
+
+
+    # ------------------------------------------------------------------
+    # internal
+    # ------------------------------------------------------------------
+    def _key_for(self, cipher: dict) -> VwCryptoKey:
+        oid = cipher.get("organizationId")
+        if oid and oid in self._org_keys:
+            return self._org_keys[oid]
+        return self._crypto_key
+
+    def _ensure_unlocked(self):
+        if not self._crypto_key:
+            self.unlock()
+
+    def _rebuild_name_cache(self):
+        self._ensure_unlocked()
+        if self._name_cache is not None:
+            return
+        d: dict[str, dict] = {}
+        for c in self._ciphers:
+            cn = decrypt(c.get("name", ""), self._key_for(c))
+            d[cn.lower()] = c
+        self._name_cache = d
+
+    def _find_cipher(self, name: str) -> dict:
+        self._rebuild_name_cache()
+        assert self._name_cache is not None
+        target = name.lower()
+        if target in self._name_cache:
+            return self._name_cache[target]
+        for key, c in self._name_cache.items():
+            if target in key:
+                return c
+        raise VwError(f"item '{name}' not found")
+
+    # ------------------------------------------------------------------
+    # get password
+    # ------------------------------------------------------------------
+    def get_password(self, name: str) -> str:
+        c = self._find_cipher(name)
+        enc_pw = (c.get("login") or {}).get("password", "")
+        if not enc_pw:
+            return ""
+        return decrypt(enc_pw, self._key_for(c))
+
+    # ------------------------------------------------------------------
+    # list
+    # ------------------------------------------------------------------
+    def list_names(self) -> list[str]:
+        self._rebuild_name_cache()
+        assert self._name_cache is not None
+        return sorted(self._name_cache.keys())
+
+    # ------------------------------------------------------------------
+    # get item
+    # ------------------------------------------------------------------
+    def get_item(self, name: str) -> dict:
+        c = self._find_cipher(name)
+        k = self._key_for(c)
+
+        def d(s: str) -> str:
+            return decrypt(s, k) if s else ""
+
+        out: dict = {"id": c.get("id")}
+        for f in ("name", "notes"):
+            if c.get(f):
+                out[f] = d(c[f])
+        if "login" in c:
+            li = c["login"]
+            lo: dict = {}
+            for f in ("username", "password", "totp"):
+                if li.get(f):
+                    lo[f] = d(li[f])
+            out["login"] = lo
+        if "fields" in c:
+            out["fields"] = [
+                {"name": d(f.get("name", "")),
+                 "value": d(f.get("value", "")),
+                 "type": f.get("type")}
+                for f in c["fields"]
+            ]
+        return out

vw_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: vw-cli
+Version: 0.2.0
+Summary: Lightweight Vaultwarden (Bitwarden-compatible) CLI in Python
+Author-email: Roberta Brandao <roberta@betabrandao.com.br>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/betabrandao/vaultvarden-cli
+Project-URL: Repository, https://gitlab.com/betabrandao/vaultvarden-cli
+Keywords: bitwarden,vaultwarden,cli,password-manager,alpine
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: cryptography>=41
+Requires-Dist: argon2-cffi>=23
+Dynamic: license-file
+
+# vw-cli
+
+Lightweight Vaultwarden (Bitwarden-compatible) CLI written in Python.  
+Authenticates via API key, syncs the vault, derives the encryption key
+locally, and prints decrypted passwords or items — all in a single command.
+
+Designed for use in Alpine‑based Docker containers where the official
+`bw` Node.js CLI is impractical.
+
+## Quick start
+
+```sh
+pip install vw-cli
+
+export VW_SERVER=https://vault.example.com
+export VW_CLIENTID=user.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+export VW_CLIENTSECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export VW_PASSWORD="your master password"
+
+vw-cli get password "My Website"
+```
+
+## Usage
+
+```
+usage: vw-cli <command> [args]
+
+commands:
+  login                     authenticate with API key
+  sync                      sync vault and print raw JSON
+  unlock                    unlock vault (derive encryption key)
+  list                      list all item names
+  get password <item>       print password for <item>
+  get item <item>           print full decrypted <item> as JSON
+```
+
+### Commands
+
+| command | description |
+|---------|-------------|
+| `login` | Authenticate with the API key. Verifies credentials work. |
+| `sync`  | Pull the full vault (profile + all ciphers) and print raw JSON. |
+| `unlock` | Derive the master key locally and decrypt the stored symmetric key. |
+| `list` | Print every item name (lowercased), one per line. |
+| `get password <item>` | Print the password for the named item (empty string if none). |
+| `get item <item>` | Print the full decrypted item as JSON. |
+
+Item lookup is case‑insensitive and supports substring matching.
+
+## Environment variables
+
+| variable | required | default | description |
+|----------|----------|---------|-------------|
+| `VW_SERVER` | no | `https://vault.bitwarden.com` | Vaultwarden or Bitwarden server URL |
+| `VW_CLIENTID` | yes | — | API client ID (`user.xxx` or `org.xxx`) |
+| `VW_CLIENTSECRET` | yes | — | API client secret |
+| `VW_PASSWORD` | yes | — | Master password |
+
+When `VW_SERVER` contains `bitwarden` the official Bitwarden identity
+and API endpoints are used automatically; otherwise the same URL is used
+for both identity and API paths.
+
+## Docker example
+
+```Dockerfile
+FROM alpine:3.19
+RUN apk add --no-cache python3 py3-pip
+RUN pip install vw-cli
+```
+
+```sh
+docker run --rm \
+  -e VW_SERVER=https://vault.example.com \
+  -e VW_CLIENTID=user.xxx \
+  -e VW_CLIENTSECRET=xxx \
+  -e VW_PASSWORD="..." \
+  my-image vw-cli get password "Database"
+```
+
+## How it works
+
+1. **Login** — sends a `client_credentials` grant with the API key to
+   `{identity_url}/connect/token` and receives a bearer token.
+2. **Sync** — fetches `GET /api/sync` which returns the user profile
+   (email, KDF parameters, encrypted symmetric key) and all ciphers.
+3. **Unlock** — derives the 32‑byte master key using the password and
+   email (PBKDF2‑SHA256 or Argon2id, depending on the profile KDF), then
+   decrypts the 64‑byte symmetric key stored in the profile.
+4. **Decrypt** — splits the symmetric key into an AES‑256‑CBC encryption
+   key (first 32 bytes) and an HMAC‑SHA256 MAC key (last 32 bytes), then
+   decrypts individual cipher fields.
+
+All key derivation happens **locally** — no unlock endpoint is called.
+
+## Architecture
+
+```
+vw_cli/
+├── __init__.py     # package entry, re‑exports
+├── __main__.py     # python -m vw_cli support
+├── error.py        # VwError exception class
+├── crypto.py       # VwCryptoKey, key derivation, AES-CBC, HMAC
+├── auth.py         # VwAuth – API key login, session management
+├── vault.py        # VwVault – sync, unlock, cipher operations
+└── cli.py          # CLI argument parsing, orchestration
+```
+
+Separation of concerns:
+
+| module | responsibility |
+|--------|---------------|
+| `crypto.py` | Pure functions: key derivation, encryption/decryption, data types. No I/O. |
+| `auth.py` | `VwAuth` class: HTTP session, token acquisition, request helper. |
+| `vault.py` | `VwVault` class: sync, unlock, name cache, find/get/list operations. |
+| `cli.py` | Environment variable reading, argument parsing, command dispatch. |
+
+## Development
+
+### Virtualenv (recommended)
+
+```sh
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+The package is installed in **editable mode** (`-e`), so source changes take
+effect immediately — no need to reinstall.
+
+### Run without pip
+
+You don't need to `pip install` at all.  The `__main__.py` entry point lets you
+run the CLI directly from the checkout:
+
+```sh
+python -m vw_cli get password "My Website"
+```
+
+Or set up a shell alias for convenience:
+
+```sh
+alias vw-cli='python -m vw_cli'
+```
+
+### Test
+
+```sh
+python -m pytest tests/ -v
+```
+
+### Testing
+
+Three test files covering all layers:
+
+| test file | coverage |
+|-----------|----------|
+| `tests/test_crypto.py` | `VwCryptoKey`, `_safe_int`, key derivation, AES-CBC, HMAC, `decrypt`, `decrypt_bytes`, `decode_encrypted` |
+| `tests/test_client.py` | `VwAuth` (login, errors), `VwVault` (sync, unlock, find, get, list), `_setup_urls`, network errors, timeout |
+| `tests/test_cli.py` | CLI argument parsing, help/version output, error handling, exit codes |
+
+Tests use mocks and never touch the network.
+
+### Dependencies
+
+- `requests` — HTTP client
+- `cryptography` — AES‑256‑CBC via OpenSSL bindings
+- `argon2-cffi` — Argon2id KDF (optional; falls back gracefully)
+
+## License
+
+MIT

vw_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vw_cli/__init__.py,sha256=8jVdzr6IvESIzQb5V4s--1Nht_Xc008xjYbSnnVeahw,507
+vw_cli/__main__.py,sha256=YV4Zw3I2UpQdtA26kynsxazz3sUwx4bRcPLrcUp4pSQ,36
+vw_cli/auth.py,sha256=-7YAwLBlZFLG_GFBvqfyjzADKCYDmSkrkOh1_nh3ois,4272
+vw_cli/cli.py,sha256=brtBvOu2DmAr6eGl-ux9-jnHKYR6Vyzj8NXl_u785Kc,3810
+vw_cli/crypto.py,sha256=HsvIoMsEUHC_kdby-WDJnFYYfM2M0EyVW4Sexi9NM6k,3246
+vw_cli/error.py,sha256=USoXlZfT5LdRsOueNPGIiFLcG-d6l8BPWBlYKGiZxUY,35
+vw_cli/vault.py,sha256=DS6zZQqVJYi96yE8wSkY_zMIYrprK5ZCh0UJlVRkXfk,6623
+vw_cli-0.2.0.dist-info/licenses/LICENSE,sha256=17chzbl98Pk6UP0EWBHCEeMzhXZ4kNtJJefNhbX5X_s,1107
+vw_cli-0.2.0.dist-info/METADATA,sha256=QdzSY0_CwtgasC8_acMFeqK3mm-6-ulo-soIOXK_3q4,6532
+vw_cli-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vw_cli-0.2.0.dist-info/entry_points.txt,sha256=bCBrJdd92ZiEzUA-uxWpTWvFvEome9McrZ5NXAYgAvI,43
+vw_cli-0.2.0.dist-info/top_level.txt,sha256=nID4WsHGaaMskZbzPF7W2WxW0fsvvjg2kg3oqcZZZxc,7
+vw_cli-0.2.0.dist-info/RECORD,,

vw_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vw_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vw-cli = vw_cli.cli:main

vw_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2026 robertanrbrandao[at]gmail[dot]com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

vw_cli-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vw_cli