@propper-ai/cli 0.2.1

package/README.md

@@ -0,0 +1,255 @@
+# propper-cli
+
+**`propper`** — an AWS-style, OpenAPI-generated command-line interface for the
+Propper Sign + Auth APIs.
+
+The API command tree is **auto-generated** from Propper's published OpenAPI specs
+(the AWS-CLI / botocore pattern): a build-time generator turns the specs into a
+JSON command manifest + a typed HTTP client, and a `commander` runtime builds the
+commands from the manifest. The generated client is exported, so it doubles as an
+importable **Sign SDK**. A scheduled GitHub Action keeps the CLI in sync with the
+specs automatically.
+
+## Install
+
+```bash
+npx @propper-ai/cli --help
+# or
+npm install -g @propper-ai/cli
+propper --help
+```
+
+Requires Node.js 20+.
+
+## Quick start
+
+```bash
+# 1. Log in (opens a browser; OAuth2 Authorization Code + PKCE)
+propper auth login
+
+# 2. Confirm who you are
+propper auth status          # alias: propper auth whoami
+
+# 3. Use the APIs (propper <api> <topic> <command>)
+propper sign agreements list --output table
+propper sign agreements get --id ag_123
+propper sign agreements create --name "NDA" --input-json @nda.json
+propper sign audit certificate --agreement-id ag_123 --output-file audit.pdf
+propper docgen batches list
+propper locker risks list
+```
+
+## Authentication
+
+`propper auth login` supports three modes:
+
+| Mode | Command | Notes |
+| --- | --- | --- |
+| Browser (PKCE) | `propper auth login` | OAuth2 Authorization Code + PKCE over a loopback redirect (RFC 8252). Default. Uses the CLI's fixed public client id. |
+| Client credentials | `propper auth login --client-credentials` | Headless / CI. Uses the configured machine `client_id` (`--client-id` / `PROPPER_CLIENT_ID` / `propper configure`) + a stored or `PROPPER_CLIENT_SECRET` secret. |
+| Pasted token | `propper auth login --token <jwt>` | Fallback. |
+
+Tokens are stored per-profile in `~/.propper/credentials.json` (chmod 600) and
+refreshed automatically. `propper auth logout` revokes and clears them.
+
+**Scopes.** By default login requests the full set of scopes the `propper-cli`
+OAuth client is allowed (`openid email profile offline_access` plus the
+`sign`, `click`, `docgen`, `locker`, and `org:read` API scopes), so the issued
+token can call every product API. Narrow the request with `--scope` (a single
+space-separated string), e.g. `propper auth login --scope "openid offline_access
+sign:read"`. The auth server still intersects whatever you request against the
+client's allow-list. Check the granted scopes with `propper auth status`.
+
+**Credential resolution order** (first match wins, AWS-style):
+
+1. `--token <jwt>`
+2. `PROPPER_API_TOKEN`
+3. stored OAuth tokens for the active profile (auto-refreshed)
+4. client-credentials grant — the machine `client_id` (`--client-id` / `PROPPER_CLIENT_ID` / config) + a stored client secret or `PROPPER_CLIENT_SECRET`
+
+> **Client ids.** The OAuth client used for browser login is a fixed, built-in
+> public client and is **not** configurable. The `client_id` you set via
+> `--client-id`, `PROPPER_CLIENT_ID`, or `propper configure` is a *separate*
+> machine-to-machine (client-credentials) client, paired with `client_secret`.
+
+## Configuration & profiles
+
+```bash
+propper configure                     # interactive wizard
+propper configure set output table    # set a value for the active profile
+propper configure get api_base_url
+propper configure list-profiles
+propper --profile staging agreements list
+```
+
+Config lives in `~/.propper/`:
+
+- `config.json` — non-secret per-profile settings (`api_base_url`, `auth_base_url`,
+  `client_id`, `output`, default profile)
+- `credentials.json` — secret tokens and the client secret (chmod 600)
+
+The interactive wizard configures, AWS-style, a machine-to-machine `client_id` +
+`client_secret` for headless / service accounts. The secret is written to
+`credentials.json`, never `config.json`. You can also set keys non-interactively:
+
+```bash
+propper configure set client_id <id>           # -> config.json
+propper configure set client_secret <secret>   # -> credentials.json (chmod 600)
+```
+
+The `client_id` and `client_secret` are stripped of all whitespace (including
+newlines and carriage returns) on input, so a pasted value with a stray trailing
+newline won't break auth.
+
+### Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `PROPPER_API_TOKEN` | Bearer token override |
+| `PROPPER_PROFILE` | Active profile |
+| `PROPPER_BASE_URL` | API base URL override |
+| `PROPPER_AUTH_BASE_URL` | Auth base URL override |
+| `PROPPER_CLIENT_ID` | Client-credentials (M2M) client id (also `--client-id`) |
+| `PROPPER_CLIENT_SECRET` | Client-credentials (M2M) client secret |
+| `PROPPER_CONFIG_DIR` | Config directory (default `~/.propper`) |
+| `PROPPER_DOCS_BASE_URL` | Spec source for `sync-spec` (default `https://docs.propper.ai`) |
+| `NO_COLOR` | Disable colored output |
+
+## Commands
+
+Commands are namespaced by API: `propper <api> <topic> <command>`. The API
+command tree is generated from each product's OpenAPI spec.
+
+```
+# sign  (Sign API, /v1/sign)
+propper sign agreements   list | create | get | update | delete | send | void |
+                          status | download | set-annotations | gen-and-send
+propper sign recipients   list | add | update | delete
+propper sign documents    list | upload | get | delete | download | download-url
+propper sign templates    list | create | get | import | export | send | ...
+propper sign audit        trail | certificate
+
+# docgen  (Propper Gen API, /v1/docgen)
+propper docgen approvals | batches | delivery-configs | documents | templates ...
+
+# locker  (Propper Locker API, /v1/locker)
+propper locker chat | documents | risks | settings ...
+```
+
+Run any group bare (`propper`, `propper sign`, `propper sign agreements`) to see
+its help.
+
+Hand-authored:
+
+```
+propper auth         login | logout | status (whoami)
+propper configure    [wizard] | set | get | list-profiles
+propper completion   bash | zsh | fish
+```
+
+> **Adding more APIs** is a one-line change in `scripts/generate.ts`
+> (`PRODUCT_SPECS`).
+
+### Global options
+
+`--profile`, `--output json|table|yaml|text`, `--query <jmespath>` (like AWS
+`--query`), `--base-url`, `--auth-base-url`, `--client-id`, `--token`,
+`--no-color`, `--quiet`, `--debug`.
+
+### Request bodies & files
+
+- Generated `--<field>` flags cover top-level scalar fields.
+- `--input-json '<json>'`, `--input-json @file.json`, or `--input-json -` (stdin)
+  set the whole body (mirrors AWS `--cli-input-json`).
+- `--file <path>` base64-encodes a local file into the relevant body field
+  (uploads, template import).
+- `--output-file <path>` writes binary responses (PDF/ZIP) to disk.
+- `--all` auto-paginates list endpoints.
+
+```bash
+propper sign agreements list --query "[?status=='sent'].id" --output text
+propper sign documents upload --agreement-id ag_123 --file ./contract.pdf --filename contract.pdf
+echo '{"name":"MSA"}' | propper sign agreements create --input-json -
+```
+
+## Use as a library (SDK)
+
+The generated client is API-namespaced and exported as `@propper-ai/cli/generated/client`:
+
+```ts
+import { operations } from "@propper-ai/cli/generated/client";
+
+const ctx = { apiBaseUrl: "https://api.propper.ai", token, userAgent: "my-app/1.0" };
+const agreements = await operations.sign.listAgreements({ query: { limit: 10 } }, ctx);
+const batches = await operations.docgen.listBatches({}, ctx);
+console.log(agreements.data, batches.data);
+```
+
+## Development
+
+```bash
+npm install
+npm run dev -- --help     # run from source
+npm test                  # vitest
+npm run lint              # biome
+npm run typecheck         # tsc
+npm run build             # tsup -> dist/
+
+npm run sync-spec         # refresh vendored specs from docs.propper.ai
+npm run generate          # regenerate src/generated/* from openapi/*
+```
+
+### Install the CLI locally from source
+
+Build, then install this checkout globally so the `propper` command is on your
+`PATH` exactly as `npm install -g @propper-ai/cli` would put it.
+
+One-shot shortcut (install deps → build → global install):
+
+```bash
+git clone https://github.com/mypropper/propper-cli.git
+cd propper-cli
+npm run dev:setup-local   # = npm install && npm run build && npm install -g .
+
+propper --version         # now available anywhere
+which propper
+```
+
+Equivalent manual steps:
+
+```bash
+npm install
+npm run build
+npm install -g .          # installs the local build globally as `propper`
+```
+
+To uninstall: `npm run dev:uninstall-local` (= `npm uninstall -g @propper-ai/cli`).
+
+**For active development** use the link shortcut instead — it symlinks the global
+`propper` to your working copy, so it picks up changes after each `npm run build`
+(no reinstall):
+
+```bash
+npm run dev:link-local  # = npm install && npm run build && npm link
+npm run build           # rebuild after edits; `propper` reflects the new build
+# ...
+npm unlink -g @propper-ai/cli   # remove the symlink when done
+```
+
+> Tip: while iterating you can skip the global install entirely and run from
+> source with `npm run dev -- <args>` (e.g. `npm run dev -- agreements list`).
+
+The generator output in `src/generated/` is committed; CI fails if it drifts from
+the vendored specs (`npm run generate` must produce no diff).
+
+### Keeping in sync with the API
+
+`.github/workflows/spec-sync.yml` runs daily: it syncs the specs, regenerates,
+validates (lint + typecheck + test + build), and opens/updates a single
+`automation/spec-sync` PR summarizing the command changes whenever the API drifts.
+No drift means no PR. Set a `SPEC_SYNC_TOKEN` secret (PAT or GitHub App token) if
+you want CI to run on the auto-PR.
+
+## License
+
+MIT