morning-cli 0.1.0__tar.gz

morning_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JangoAI (https://jango-ai.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.

morning_cli-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: morning-cli
+Version: 0.1.0
+Summary: Agent-native CLI for the morning by Green Invoice REST API — 66 endpoints, JSON envelopes, sandbox-first, built by JangoAI.
+Home-page: https://github.com/jango-ai-com/morning-cli
+Author: JangoAI
+Author-email: hello@jango-ai.com
+License: MIT
+Project-URL: Homepage, https://jango-ai.com
+Project-URL: Source, https://github.com/jango-ai-com/morning-cli
+Project-URL: Tracker, https://github.com/jango-ai-com/morning-cli/issues
+Project-URL: morning API docs, https://www.greeninvoice.co.il/api-docs
+Keywords: morning,green-invoice,greeninvoice,invoicing,israel,rest-api,cli,agent,cli-anything,jangoai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Hebrew
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich>=13.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# morning-cli
+
+**Agent-native command-line interface for [morning by Green Invoice](https://www.greeninvoice.co.il) — Israel's leading invoicing SaaS.**
+
+Built by [JangoAI](https://jango-ai.com) using the [cli-anything](https://github.com/HKUDS/CLI-Anything) methodology. Hebrew README: [README.he.md](README.he.md).
+
+- **66 endpoints** across 10 resource groups (Businesses, Clients, Suppliers, Items, Documents, Expenses, Payments, Partners, Tools)
+- **Interactive setup wizard** — `morning-cli auth init` walks you through API key creation
+- **REPL** as the default mode — run `morning-cli` with no args
+- **`--json` envelopes** for AI-agent consumption — stable shape, documented error codes
+- **Automatic JWT refresh** on 401, with transparent retry
+- **Sandbox-first** — default environment is sandbox so accidents don't touch production
+- **Locked session file** at `~/.greeninvoice/session.json` (mode 0600)
+- **55 tests**, including 22 end-to-end against the real sandbox API
+- **Hebrew error messages** preserved end-to-end
+
+## Install
+
+```bash
+pip install morning-cli
+```
+
+Python 3.10+ required.
+
+## Quick start
+
+```bash
+# 1. Run the interactive onboarding wizard
+morning-cli auth init
+
+# 2. Try the REPL
+morning-cli
+
+# Or use one-shot commands
+morning-cli --json business current
+morning-cli --json document types --lang he
+morning-cli --json client search
+```
+
+### What `auth init` does
+
+```
+ morning-cli setup wizard
+ ──────────────────────────
+
+ Step 1/4 — choose environment
+   sandbox    (recommended — safe, no real money)
+   production (live data)
+   env [sandbox]:
+
+ Step 2/4 — get your API keys (sandbox)
+   Open this URL in your browser and log in:
+
+     https://app.sandbox.d.greeninvoice.co.il/settings/developers/api
+
+   Then: Settings → Advanced → Developers → 'יצירת מפתח API'
+   Copy the ID and the Secret. The Secret is shown ONCE — save it now.
+
+ Step 3/4 — paste your credentials
+   API Key ID:     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+   API Key Secret: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●
+
+ Step 4/4 — verifying against the real API...
+   ✓ Authenticated successfully
+   business:    Your Business Name
+   business_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+   env:         sandbox
+   saved to:    ~/.greeninvoice/credentials.json
+
+   All set. Try:
+     morning-cli business current
+     morning-cli --json document types --lang he
+     morning-cli                      # interactive REPL
+```
+
+The wizard saves your keys to `~/.greeninvoice/credentials.json` (mode 0600) and verifies them live before writing anything.
+
+### Non-interactive setup (for scripts and CI)
+
+```bash
+export MORNING_API_KEY_ID=<your-id>
+export MORNING_API_KEY_SECRET=<your-secret>
+export MORNING_ENV=sandbox          # or production
+morning-cli auth init --non-interactive --force
+```
+
+The legacy prefix `GREENINVOICE_*` is also supported for backwards compatibility.
+
+## Commands
+
+| Group | Endpoints | Key commands |
+|---|---|---|
+| `auth` | local | `init` (wizard), `login`, `logout`, `whoami`, `refresh` |
+| `session` | local | `show`, `reset`, `history` |
+| `business` | 10 | `list`, `current`, `get`, `update`, `numbering-get`, `numbering-update`, `file-upload`, `file-delete`, `footer`, `types` |
+| `client` | 8 | `add`, `get`, `update`, `delete`, `search`, `assoc`, `merge`, `balance` |
+| `supplier` | 6 | `add`, `get`, `update`, `delete`, `search`, `merge` |
+| `item` | 5 | `add`, `get`, `update`, `delete`, `search` |
+| `document` | 13 | `create`, `preview`, `get`, `search`, `close`, `open`, `linked`, `download`, `info`, `types`, `statuses`, `templates`, `payments-search` |
+| `expense` | 13 | `add`, `get`, `update`, `delete`, `search`, `open`, `close`, `statuses`, `accounting-classifications`, `file-url`, `draft-from-file`, `update-file`, `drafts-search` |
+| `payment` | 3 | `form`, `tokens-search`, `charge` |
+| `partner` | 4 | `users`, `connect`, `get`, `disconnect` |
+| `tools` | 4 | `occupations`, `countries`, `cities`, `currencies` |
+
+### Passing JSON bodies
+
+Any command that needs a request body accepts either `--data '<json>'` or `--file path/to/body.json`:
+
+```bash
+morning-cli --json client add --data '{"name":"Acme","emails":["x@y.com"],"taxCode":1}'
+morning-cli --json document create --file invoice.json
+```
+
+### Example — create a proforma invoice (חשבון עסקה)
+
+```bash
+cat > /tmp/proforma.json <<'JSON'
+{
+  "description": "Monthly retainer",
+  "type": 300,
+  "lang": "he",
+  "currency": "ILS",
+  "vatType": 0,
+  "client": {"name": "Acme Ltd", "emails": ["ap@acme.com"], "country": "IL"},
+  "income": [
+    {"description": "שירותי ייעוץ", "quantity": 10, "price": 300, "currency": "ILS", "vatType": 0}
+  ]
+}
+JSON
+morning-cli --json document preview --file /tmp/proforma.json
+morning-cli --json document create --file /tmp/proforma.json
+```
+
+## Output envelope (for agents)
+
+Every `--json` command returns a consistent envelope:
+
+```json
+{"ok": true, "op": "document.create", "data": {"id": "...", "number": 12345}}
+```
+
+Errors carry the Green Invoice `errorCode` and the (Hebrew) `errorMessage`:
+
+```json
+{"ok": false, "op": "document.create", "error": {"code": 1110, "message": "מחיר לא תקין.", "http_status": 400}}
+```
+
+**Exit codes:** `0` ok · `1` usage/local error · `2` API error · `3` 5xx/network
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `MORNING_API_KEY_ID` | API key ID (fallback: `GREENINVOICE_API_KEY_ID`) |
+| `MORNING_API_KEY_SECRET` | API key secret (fallback: `GREENINVOICE_API_KEY_SECRET`) |
+| `MORNING_ENV` | `sandbox` or `production` (fallback: `GREENINVOICE_ENV`, default `sandbox`) |
+| `MORNING_BASE_URL` | Override base URL entirely (proxies, custom deploys) |
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+
+# Unit tests — no network
+pytest cli_anything/greeninvoice/tests/test_core.py -v
+
+# Full suite including live sandbox E2E
+export MORNING_SANDBOX_ID=<your-sandbox-id>
+export MORNING_SANDBOX_SECRET=<your-sandbox-secret>
+CLI_ANYTHING_FORCE_INSTALLED=1 pytest cli_anything/greeninvoice/tests/ -v
+```
+
+**55 tests** — 27 unit tests (mock `httpx`) + 4 offline E2E (help, version, error envelopes) + 22 live sandbox E2E (auth, business, documents, items, suppliers, expenses, tools, read-only smoke across all 10 resource groups). See [tests/TEST.md](cli_anything/greeninvoice/tests/TEST.md) for the full plan and results.
+
+## Methodology
+
+Built with the cli-anything 7-phase SOP:
+
+1. **Codebase analysis** — parsed Apiary spec → 66 endpoints mapped
+2. **Architecture** — 10 resource groups + local auth/session, REPL-first
+3. **Implementation** — Python namespace package `cli_anything.greeninvoice`
+4. **Test planning** — `tests/TEST.md`
+5. **Test implementation** — unit + live E2E
+6. **Test documentation** — results captured
+7. **PyPI publishing** — `pip install morning-cli`
+
+Full methodology in [GREENINVOICE.md](GREENINVOICE.md).
+
+## For AI agents
+
+`morning-cli` ships with a [SKILL.md](cli_anything/greeninvoice/skills/SKILL.md) file that's auto-discovered by the REPL banner and Claude Code / Cursor. If you're an agent reading this, check the skill file first — it has concrete invocation examples and Green Invoice error code references.
+
+## Contributing
+
+PRs welcome at [github.com/jango-ai-com/morning-cli](https://github.com/jango-ai-com/morning-cli). Run the tests before submitting:
+
+```bash
+pip install -e ".[test]"
+pytest cli_anything/greeninvoice/tests/test_core.py -v
+```
+
+## About JangoAI
+
+[JangoAI](https://jango-ai.com) is an Israeli AI automation studio. We build agent-native tooling for Israeli developers and businesses — n8n workflows, Monday.com integrations, Supabase data models, and CLIs like this one.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+*Created by JangoAI · [jango-ai.com](https://jango-ai.com) · [@jango-ai-com on GitHub](https://github.com/jango-ai-com)*

morning_cli-0.1.0/README.md

@@ -0,0 +1,212 @@
+# morning-cli
+
+**Agent-native command-line interface for [morning by Green Invoice](https://www.greeninvoice.co.il) — Israel's leading invoicing SaaS.**
+
+Built by [JangoAI](https://jango-ai.com) using the [cli-anything](https://github.com/HKUDS/CLI-Anything) methodology. Hebrew README: [README.he.md](README.he.md).
+
+- **66 endpoints** across 10 resource groups (Businesses, Clients, Suppliers, Items, Documents, Expenses, Payments, Partners, Tools)
+- **Interactive setup wizard** — `morning-cli auth init` walks you through API key creation
+- **REPL** as the default mode — run `morning-cli` with no args
+- **`--json` envelopes** for AI-agent consumption — stable shape, documented error codes
+- **Automatic JWT refresh** on 401, with transparent retry
+- **Sandbox-first** — default environment is sandbox so accidents don't touch production
+- **Locked session file** at `~/.greeninvoice/session.json` (mode 0600)
+- **55 tests**, including 22 end-to-end against the real sandbox API
+- **Hebrew error messages** preserved end-to-end
+
+## Install
+
+```bash
+pip install morning-cli
+```
+
+Python 3.10+ required.
+
+## Quick start
+
+```bash
+# 1. Run the interactive onboarding wizard
+morning-cli auth init
+
+# 2. Try the REPL
+morning-cli
+
+# Or use one-shot commands
+morning-cli --json business current
+morning-cli --json document types --lang he
+morning-cli --json client search
+```
+
+### What `auth init` does
+
+```
+ morning-cli setup wizard
+ ──────────────────────────
+
+ Step 1/4 — choose environment
+   sandbox    (recommended — safe, no real money)
+   production (live data)
+   env [sandbox]:
+
+ Step 2/4 — get your API keys (sandbox)
+   Open this URL in your browser and log in:
+
+     https://app.sandbox.d.greeninvoice.co.il/settings/developers/api
+
+   Then: Settings → Advanced → Developers → 'יצירת מפתח API'
+   Copy the ID and the Secret. The Secret is shown ONCE — save it now.
+
+ Step 3/4 — paste your credentials
+   API Key ID:     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+   API Key Secret: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●
+
+ Step 4/4 — verifying against the real API...
+   ✓ Authenticated successfully
+   business:    Your Business Name
+   business_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+   env:         sandbox
+   saved to:    ~/.greeninvoice/credentials.json
+
+   All set. Try:
+     morning-cli business current
+     morning-cli --json document types --lang he
+     morning-cli                      # interactive REPL
+```
+
+The wizard saves your keys to `~/.greeninvoice/credentials.json` (mode 0600) and verifies them live before writing anything.
+
+### Non-interactive setup (for scripts and CI)
+
+```bash
+export MORNING_API_KEY_ID=<your-id>
+export MORNING_API_KEY_SECRET=<your-secret>
+export MORNING_ENV=sandbox          # or production
+morning-cli auth init --non-interactive --force
+```
+
+The legacy prefix `GREENINVOICE_*` is also supported for backwards compatibility.
+
+## Commands
+
+| Group | Endpoints | Key commands |
+|---|---|---|
+| `auth` | local | `init` (wizard), `login`, `logout`, `whoami`, `refresh` |
+| `session` | local | `show`, `reset`, `history` |
+| `business` | 10 | `list`, `current`, `get`, `update`, `numbering-get`, `numbering-update`, `file-upload`, `file-delete`, `footer`, `types` |
+| `client` | 8 | `add`, `get`, `update`, `delete`, `search`, `assoc`, `merge`, `balance` |
+| `supplier` | 6 | `add`, `get`, `update`, `delete`, `search`, `merge` |
+| `item` | 5 | `add`, `get`, `update`, `delete`, `search` |
+| `document` | 13 | `create`, `preview`, `get`, `search`, `close`, `open`, `linked`, `download`, `info`, `types`, `statuses`, `templates`, `payments-search` |
+| `expense` | 13 | `add`, `get`, `update`, `delete`, `search`, `open`, `close`, `statuses`, `accounting-classifications`, `file-url`, `draft-from-file`, `update-file`, `drafts-search` |
+| `payment` | 3 | `form`, `tokens-search`, `charge` |
+| `partner` | 4 | `users`, `connect`, `get`, `disconnect` |
+| `tools` | 4 | `occupations`, `countries`, `cities`, `currencies` |
+
+### Passing JSON bodies
+
+Any command that needs a request body accepts either `--data '<json>'` or `--file path/to/body.json`:
+
+```bash
+morning-cli --json client add --data '{"name":"Acme","emails":["x@y.com"],"taxCode":1}'
+morning-cli --json document create --file invoice.json
+```
+
+### Example — create a proforma invoice (חשבון עסקה)
+
+```bash
+cat > /tmp/proforma.json <<'JSON'
+{
+  "description": "Monthly retainer",
+  "type": 300,
+  "lang": "he",
+  "currency": "ILS",
+  "vatType": 0,
+  "client": {"name": "Acme Ltd", "emails": ["ap@acme.com"], "country": "IL"},
+  "income": [
+    {"description": "שירותי ייעוץ", "quantity": 10, "price": 300, "currency": "ILS", "vatType": 0}
+  ]
+}
+JSON
+morning-cli --json document preview --file /tmp/proforma.json
+morning-cli --json document create --file /tmp/proforma.json
+```
+
+## Output envelope (for agents)
+
+Every `--json` command returns a consistent envelope:
+
+```json
+{"ok": true, "op": "document.create", "data": {"id": "...", "number": 12345}}
+```
+
+Errors carry the Green Invoice `errorCode` and the (Hebrew) `errorMessage`:
+
+```json
+{"ok": false, "op": "document.create", "error": {"code": 1110, "message": "מחיר לא תקין.", "http_status": 400}}
+```
+
+**Exit codes:** `0` ok · `1` usage/local error · `2` API error · `3` 5xx/network
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `MORNING_API_KEY_ID` | API key ID (fallback: `GREENINVOICE_API_KEY_ID`) |
+| `MORNING_API_KEY_SECRET` | API key secret (fallback: `GREENINVOICE_API_KEY_SECRET`) |
+| `MORNING_ENV` | `sandbox` or `production` (fallback: `GREENINVOICE_ENV`, default `sandbox`) |
+| `MORNING_BASE_URL` | Override base URL entirely (proxies, custom deploys) |
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+
+# Unit tests — no network
+pytest cli_anything/greeninvoice/tests/test_core.py -v
+
+# Full suite including live sandbox E2E
+export MORNING_SANDBOX_ID=<your-sandbox-id>
+export MORNING_SANDBOX_SECRET=<your-sandbox-secret>
+CLI_ANYTHING_FORCE_INSTALLED=1 pytest cli_anything/greeninvoice/tests/ -v
+```
+
+**55 tests** — 27 unit tests (mock `httpx`) + 4 offline E2E (help, version, error envelopes) + 22 live sandbox E2E (auth, business, documents, items, suppliers, expenses, tools, read-only smoke across all 10 resource groups). See [tests/TEST.md](cli_anything/greeninvoice/tests/TEST.md) for the full plan and results.
+
+## Methodology
+
+Built with the cli-anything 7-phase SOP:
+
+1. **Codebase analysis** — parsed Apiary spec → 66 endpoints mapped
+2. **Architecture** — 10 resource groups + local auth/session, REPL-first
+3. **Implementation** — Python namespace package `cli_anything.greeninvoice`
+4. **Test planning** — `tests/TEST.md`
+5. **Test implementation** — unit + live E2E
+6. **Test documentation** — results captured
+7. **PyPI publishing** — `pip install morning-cli`
+
+Full methodology in [GREENINVOICE.md](GREENINVOICE.md).
+
+## For AI agents
+
+`morning-cli` ships with a [SKILL.md](cli_anything/greeninvoice/skills/SKILL.md) file that's auto-discovered by the REPL banner and Claude Code / Cursor. If you're an agent reading this, check the skill file first — it has concrete invocation examples and Green Invoice error code references.
+
+## Contributing
+
+PRs welcome at [github.com/jango-ai-com/morning-cli](https://github.com/jango-ai-com/morning-cli). Run the tests before submitting:
+
+```bash
+pip install -e ".[test]"
+pytest cli_anything/greeninvoice/tests/test_core.py -v
+```
+
+## About JangoAI
+
+[JangoAI](https://jango-ai.com) is an Israeli AI automation studio. We build agent-native tooling for Israeli developers and businesses — n8n workflows, Monday.com integrations, Supabase data models, and CLIs like this one.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+*Created by JangoAI · [jango-ai.com](https://jango-ai.com) · [@jango-ai-com on GitHub](https://github.com/jango-ai-com)*

morning_cli-0.1.0/cli_anything/greeninvoice/README.md

@@ -0,0 +1,33 @@
+# morning-cli (Python package)
+
+Installed sub-package under the `cli_anything.greeninvoice` namespace.
+
+## Install
+
+```bash
+pip install morning-cli
+# or, from source:
+pip install -e .
+```
+
+Two console scripts are registered:
+- `morning-cli` — primary user-facing command
+- `cli-anything-greeninvoice` — alias preserved for cli-anything methodology compat
+
+## Run
+
+```bash
+morning-cli                  # REPL (default)
+morning-cli auth init        # interactive setup wizard
+morning-cli --help           # command reference
+morning-cli --json business current
+```
+
+## About
+
+Built by [JangoAI](https://jango-ai.com) using the
+[cli-anything](https://github.com/HKUDS/CLI-Anything) methodology.
+
+See the top-level [README.md](../../README.md) and
+[GREENINVOICE.md](../../GREENINVOICE.md) for full usage, architecture, and
+credential setup.

morning_cli-0.1.0/cli_anything/greeninvoice/__init__.py

@@ -0,0 +1,11 @@
+"""morning-cli — agent-native CLI for the morning by Green Invoice REST API.
+
+Built by JangoAI (https://jango-ai.com) with the cli-anything methodology.
+The Python namespace ``cli_anything.greeninvoice`` is intentional and follows
+PEP 420 namespace packaging so multiple ``cli-anything-<software>`` harnesses
+can coexist. User-facing name on PyPI and on PATH: ``morning-cli``.
+"""
+
+__version__ = "0.1.0"
+__author__ = "JangoAI"
+__url__ = "https://jango-ai.com"

morning_cli-0.1.0/cli_anything/greeninvoice/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m cli_anything.greeninvoice``."""
+
+from cli_anything.greeninvoice.greeninvoice_cli import cli
+
+if __name__ == "__main__":
+    cli()

morning_cli-0.1.0/cli_anything/greeninvoice/core/auth.py

@@ -0,0 +1,138 @@
+"""Authentication primitives (token acquire/refresh/whoami + onboarding).
+
+These live at the core layer so both the CLI and the REPL can call them
+without importing Click.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from cli_anything.greeninvoice.utils.greeninvoice_backend import (
+    CREDENTIALS_PATH,
+    ENVIRONMENTS,
+    GreenInvoiceAPIError,
+    GreenInvoiceBackend,
+    GreenInvoiceError,
+    find_credentials,
+)
+
+# URLs pointing at the morning dashboard API-keys screen, for the wizard
+# to deep-link users to the right place.
+DASHBOARD_URLS = {
+    "production": "https://app.greeninvoice.co.il/settings/developers/api",
+    "sandbox": "https://app.sandbox.d.greeninvoice.co.il/settings/developers/api",
+}
+
+
+def login(session: dict[str, Any], env: str | None = None) -> dict[str, Any]:
+    """Force-acquire a fresh token and cache it in ``session``."""
+    backend = GreenInvoiceBackend.from_session(session, env_override=env)
+    try:
+        backend.acquire_token(force=True)
+    finally:
+        backend.close()
+    return session["token"]
+
+
+def logout(session: dict[str, Any]) -> None:
+    """Drop the cached token (but keep api_key_id + env context)."""
+    session["token"] = None
+
+
+def verify_credentials(
+    api_key_id: str,
+    api_key_secret: str,
+    env: str,
+    base_url_override: str | None = None,
+) -> dict[str, Any]:
+    """Probe a pair of credentials against the real API.
+
+    Returns a dict with {token, expires_at, business_name, business_id}.
+    Raises ``GreenInvoiceAPIError`` on a bad key pair, or
+    ``GreenInvoiceError`` on network issues / unexpected responses.
+    """
+    base_url = base_url_override or ENVIRONMENTS.get(env)
+    if not base_url:
+        raise GreenInvoiceError(f"Unknown env {env!r}")
+
+    probe_session: dict[str, Any] = {}
+    client = httpx.Client(
+        timeout=30.0,
+        headers={"User-Agent": "morning-cli/auth-init (+https://jango-ai.com)"},
+    )
+    backend = GreenInvoiceBackend(
+        api_key_id=api_key_id,
+        api_key_secret=api_key_secret,
+        base_url=base_url,
+        session=probe_session,
+        client=client,
+    )
+    try:
+        token = backend.acquire_token(force=True)
+        business = backend.get("/businesses/me")
+    finally:
+        backend.close()
+
+    result = {
+        "token": token,
+        "expires_at": probe_session["token"]["expires_at"],
+        "business_name": (business or {}).get("name") if isinstance(business, dict) else None,
+        "business_id": (business or {}).get("id") if isinstance(business, dict) else None,
+        "base_url": base_url,
+    }
+    return result
+
+
+def write_credentials_file(
+    api_key_id: str,
+    api_key_secret: str,
+    env: str,
+    path: Path | None = None,
+) -> Path:
+    """Write credentials JSON with 0600 perms. Returns the written path."""
+    target = path or CREDENTIALS_PATH
+    target.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        target.parent.chmod(0o700)
+    except PermissionError:
+        pass
+
+    payload = {"id": api_key_id, "secret": api_key_secret, "env": env}
+    # Atomic-ish write: write to tmp then rename, with strict perms.
+    tmp = target.with_suffix(target.suffix + ".tmp")
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, ensure_ascii=False, indent=2)
+    except Exception:
+        tmp.unlink(missing_ok=True)
+        raise
+    os.replace(tmp, target)
+    try:
+        target.chmod(0o600)
+    except PermissionError:
+        pass
+    return target
+
+
+def whoami(session: dict[str, Any]) -> dict[str, Any]:
+    """Return a safe view of who we'd be acting as.
+
+    Does not hit the network unless ``session.token`` is missing or expired —
+    in which case it calls ``/businesses/me`` to verify live access.
+    """
+    creds = find_credentials(env_override=session.get("env"))
+    info: dict[str, Any] = {
+        "env": creds["env"],
+        "base_url": creds["base_url"],
+        "api_key_id": creds["id"],
+        "token_cached": bool((session.get("token") or {}).get("value")),
+        "token_expires_at": (session.get("token") or {}).get("expires_at"),
+        "business_id": (session.get("context") or {}).get("business_id"),
+    }
+    return info