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 zero-knowledge crypto, a browser-approved sign-in flow that never exposes your password to the terminal, an MCP connector for AI assistants, 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. Connect an AI assistant over MCP
  4. Integrate over the OAuth 2.0 API
  5. Clone the source repositories
  6. 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 recovery-disabled client-side-decrypt boundary. Only approve codes you requested yourself, moments ago.

For the full client experience with local zero-knowledge 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. Connect an AI assistant over MCP

OWL ships a remote MCP (Model Context Protocol) endpoint at https://ndevr.org/api/owl/mcp — add it to Claude, ChatGPT, or any MCP-capable host as a remote connector. A browser GET of that URL returns 404 by design; the endpoint speaks JSON-RPC over POST.

  • Editable-link bootstrap — with no credential at all, the connector exposes open_owl_link: paste a complete editable OWL share URL as the tool's owl_link argument and the AI can inspect and (after your confirmation) edit that document. Treat the URL as the secret it is.
  • Scoped tokens — sign in with the CLI and mint a revocable token for one resource: owl ai token mint. Add it as the connector's Bearer credential. owl ai token list | revoke manage them.

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

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

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