OWL from the command line — for people and for AI agents

Everything OWL can do in the browser is scriptable: a single-file Python CLI with the full client-side (CSD) crypto, a browser-approved sign-in flow that never exposes your password to the terminal, and a scoped OAuth 2.0 API for integrations.

Agents: the machine-readable version of this page is /llms.txt.
OAuth discovery: /.well-known/oauth-authorization-server.

In a hurry? Download owl.pyz, run python3 owl.pyz help all, and sign in with python3 owl.pyz connect login — no password ever touches the terminal.

Contents

  1. Download the CLI
  2. Sign in without typing a password
  3. Full sign-in through your browser
  4. Retired link-based AI access
  5. Integrate over the OAuth 2.0 API
  6. Clone the source repositories
  7. Scripting and automation notes

1. Download the CLI

The owl CLI is a single file with no dependencies beyond Python 3.7+ — no pip installs, no config, and any Python works: the stock macOS /usr/bin/python3, distro Pythons, python.org and Homebrew builds, and whatever py launches on Windows. (An older interpreter prints exactly what to install instead of a traceback.) Crypto is pure stdlib, with an optional OpenSSL fast path that is byte-verified against the reference implementation before it is ever used. The CLI is byte-interoperable with the desktop and web clients: files it uploads, links it shares, and messages it sends use the same end-to-end encryption.

curl -fsSLO https://ndevr.org/cli/owl.pyz
python3 owl.pyz help all          # Windows: py owl.pyz help all

help all prints the complete command reference, generated from the live command tree, so it is never stale. The major groups: resource (files, folders, sharing, chat), pass (password vault), product (downloads), calendar, group, ai, and connect (scoped sign-in, below).

2. Sign in without typing a password

owl connect login uses the OAuth 2.0 device flow (RFC 8628). The terminal shows a short code and a link; you approve it in a browser where you're already signed in. The terminal — and any AI agent driving it — never sees your password.

python3 owl.pyz connect login
    To approve this sign-in, open:
        https://ndevr.org/activate?user_code=XXXX-XXXX
    and confirm the code:  XXXX-XXXX

After approval the CLI holds a scoped access token (files:read, files:write) and can list, download, and upload your files with owl connect ls | pull | push. The session expires on its own within 8 hours (or after 30 idle minutes); owl connect logout ends it immediately.

What approval means. For the session's lifetime, NDEVR's server can decrypt the files this token reaches, on your behalf — that's what lets a terminal without your password read them. This is the same consented exception used by OWL Connect integrations, and it is outside the client-side-decrypt boundary. Only approve codes you requested yourself, moments ago.

For the full client experience with local client-side (CSD) crypto (chat, the password vault, sharing), sign in with python3 owl.pyz login instead — it asks for your password locally, derives keys in-process, and the password never leaves your machine.

3. Full sign-in through your browser

owl login --web gives the terminal the full client-side-crypto session — the same one owl login produces — without typing a password or a two-factor code into it. The CLI generates a one-shot P-256 key, prints (and opens) a sign-in link, and waits. You sign in on that page with the ordinary OWL sign-in card — password, authenticator code or recovery code, exactly as on the website — and press Approve. Your browser then encrypts a fresh session token plus your unwrapped OWL keypair straight to the CLI's one-shot key; NDEVR's server relays only that ciphertext and never holds your key.

python3 owl.pyz login --web
    To sign in, open this link in a browser (it asks for your password and any two-factor code there):
        https://ndevr.org/web/qr-login.html#request_id=…
    waiting up to 5 minutes for the approval…
    logged in as you (user #…), token expires …

This is the right way to let an AI agent or a script sign the CLI in: it never sees your password, your code, or your key — it only runs the command and waits. Add --no-browser to print the link without launching a browser (for example on a machine reached over SSH; open the link on any signed-in device). The link expires after five minutes and can be used once. The resulting session behaves like any other CLI session (14 days; owl logout clears it locally).

Compared with connect login. The device flow above hands the server your key for a scoped, short-lived session. login --web keeps the key on your machine, in the CLI's local session cache, and unlocks everything the CLI can do — chat, the password vault, sharing, kanban.

4. Retired link-based AI access

Pasted-link MCP authentication, editable-link bootstrap, link-based AI token minting, and the link-based GPT Actions are retired. Do not send private share URLs to those interfaces. Existing tokens can be reviewed or revoked with owl ai token list and owl ai token revoke.

Current file sharing uses owl resource share: it generates a private catalog link whose capability remains in the URL fragment. Public installers use owl product download, which saves the versioned installer filename and verifies the response version and SHA-256. Installers do not depend on file-share links.

5. Integrate over the OAuth 2.0 API

Third-party apps use OWL Connect: an OAuth 2.0 authorization server with consented, scoped, server-side-decrypt access — metadata at /.well-known/oauth-authorization-server.

EndpointPurpose
POST /api/connect/device/codeStart a device-flow authorization (public clients)
GET /owl/connect-authorizeRedirect-based consent page (authorization code + PKCE)
POST /api/connect/tokenExchange a code — or poll a device code — for an access token
GET /api/connect/resourcesList resources visible to the token (files:read)
GET /api/connect/resource/{id}Download one resource, decrypted (files:read)
POST /api/connect/resourceUpload a new file (files:write)
POST /api/connect/revokeEnd the session now

Client registrations are issued by NDEVR — contact us to register a redirect URI and scopes for your app. Most other /api/owl/* endpoints require an OWL session plus client-side key derivation; use the CLI for those rather than raw HTTP.

6. Clone the source repositories

NDEVR's source repos (including NDEVR_Source) are self-hosted right here, served as bare git over SSH:

git clone git@ndevr.org:NDEVR_Source.git

There is no anonymous or HTTP clone: access requires an SSH public key registered with NDEVR plus a per-repo role. Roles and reviews are managed with the CLI (owl repo list | info | roles | grant, owl repo review-*), and code, history, and diffs are browsable signed-in at /owl/repos. Agents: if you're working on a machine that already has access, ~/.ssh/config typically carries a git@ndevr.org or ndevr-git host entry — check it before concluding you can't clone.

7. Scripting and automation notes

  • --json on most read commands emits machine-readable output; errors go to stderr and the exit code is 1 (usage errors: 2).
  • Text arguments accept @file and - (stdin) — use them for multiline content instead of shell escaping.
  • Non-interactive full sign-in reads $NDEVR_OWL_PASSWORD; prompts fail fast when stdin is not a TTY, so scripts never hang.
  • Self-hosted OWL servers work with --server https://your-host/; the device flow prints your host's own /activate link, and NDEVR_OWL_CONNECT_CLIENT overrides the OAuth client id.