Metadata-Version: 2.4
Name: leasevector-cli
Version: 0.2.0
Summary: Use LeaseVector from the command line
Author: Christian Vanderwall
Author-email: Christian Vanderwall <christian@leasevector.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: mcp==2.2.0
Requires-Python: >=3.14
Project-URL: Homepage, https://leasevector.com
Project-URL: Documentation, https://app.leasevector.com/account/connect/
Description-Content-Type: text/markdown

# LeaseVector CLI

`lv` brings LeaseVector's tools to the command line with your account's permissions, for scripts and for terminal AI agents such as Claude Code and Codex.

## Install

The quickest way is the one-line installer shown on the **Connect AI tools** page in LeaseVector. It installs `uv` if needed, installs this package, and runs `lv setup`:

```sh
curl -fsSL https://app.leasevector.com/install.sh | sh
```

```powershell
irm https://app.leasevector.com/install.ps1 | iex
```

To install by hand, use [uv](https://docs.astral.sh/uv/), which also provides the required Python 3.14:

```sh
uv tool install leasevector-cli
lv setup
```

Upgrade later with `uv tool upgrade leasevector-cli`. `lv --version` prints the installed version.

## Set up

`lv setup` is the whole onboarding step, and it is safe to run again at any time:

```sh
lv setup
```

Each run does two things:

1. **Signs in.** Setup opens your browser to sign in to the deployment, even if this computer is already signed in.
2. **Installs skills.** Setup looks for Claude Code (a `claude` command or a `~/.claude` directory) and Codex (a `codex` command or a `~/.codex` directory). For each one it finds, it asks whether to install the LeaseVector skill, or to reinstall it if one is already there. Reinstalling replaces the skill with a fresh copy from the deployment.

Re-run `lv setup` whenever you need to sign in again or to install or reinstall skills, for example after installing Claude Code or after LeaseVector updates its instructions.

The skill teaches an agent to use `lv`. Setup downloads it from the deployment at `/connected-agents/skill.md`, so it always matches the server's own instructions, and writes it to:

- Claude Code: `~/.claude/skills/leasevector/SKILL.md`
- Codex: `~/.agents/skills/leasevector/SKILL.md`

Setup replaces a previous LeaseVector skill, recognized by `name: leasevector` in its front matter. It never replaces any other file at those paths unless you pass `--force`.

Questions are asked on the terminal itself, not standard input, so setup can still ask when the installer is piped into a shell. When no terminal is available, setup installs no skills and says so. These options make a run non-interactive:

```sh
lv setup --skills claude-code,codex   # install or reinstall for these hosts, detected or not
lv setup --all-skills                 # install or reinstall for every detected host
lv setup --no-skills                  # sign in only; leave skills unchanged
```

## Choose a deployment

`lv` uses `https://app.leasevector.com` by default. For staging or local development, give the deployment's address, the one you open in a browser, with `--server` on any command or `LEASEVECTOR_CLI` in the environment:

```sh
export LEASEVECTOR_CLI=http://localhost:8000
lv setup --no-skills
```

Addresses must use HTTPS, except on the loopback interface, and have no path; `lv` finds the deployment's MCP endpoint itself. From a repository checkout, install the working copy with `uv tool install --reinstall ./packages/leasevector-cli`.

## Sign-in and credentials

`lv setup` and `lv login` both sign in; `lv login` leaves skills alone. Sign-in opens a browser and receives the authorization response on an ephemeral loopback port. The deployment must have its `leasevector-cli` public OAuth registration provisioned. No Django installation or settings are needed by the CLI.

Credentials are stored privately per deployment under `$XDG_CONFIG_HOME/leasevector` (by default `~/.config/leasevector`) on Linux and macOS, and under `%APPDATA%\leasevector` on Windows. Refreshes are serialized across processes. An interrupted refresh requires signing in again, so a spent refresh token is never replayed. Do not copy credential files between machines.

## Use tools

Discover the tools currently allowed for your account. Tool and parameter underscores become hyphens:

```sh
lv tools
lv list-leases --help
lv list-leases --client-id 3
lv list-leases --client-id 3 --table
lv tool list_leases --arguments '{"client_id":3,"limit":10}'
lv tool list_leases --arguments-file ./arguments.json
```

Local `lv --help` works before sign-in. Remote help and commands fetch every page of the authorized catalog on each invocation, so newly added tools need no CLI release. Names that collide with built-ins remain available through `lv tool <exact_name>`. Generated flags accept plain strings and JSON numbers, booleans, arrays, objects, and nullable values. Omitted arguments remain omitted; `null` explicitly supplies a nullable value. Use whole-arguments JSON for exact control or parameters that collide with CLI options. Full JSON cannot be mixed with generated argument flags.

Stdout contains JSON by default, preserving structured result envelopes and pagination fields. `--table` displays Page items. Validation details from the server remain in JSON; diagnostics, setup progress, and questions go to stderr or the terminal.

Commands act immediately under your account's authority; `lv` does not ask before running a tool. Approval belongs to you or to the agent host running `lv`, such as Claude Code or Codex permission modes. Tool descriptions state consequences that LeaseVector cannot undo, such as archiving a client or lease permanently invalidating its share links, and the Audit Log attributes every action to you and the connected agent. Lost mutation responses are not replayed: inspect the Audit Log before deciding whether to retry.

## Exit codes

- `0`: success.
- `2`: input, tool, or transport failure. This includes an interrupted command, a skill that `lv setup` could not download or write, and a non-LeaseVector file that `lv setup --skills` or `--all-skills` refused to replace.
- `3`: authentication failure. Run `lv login` or `lv setup`.

The CLI uses MCP SDK 2.2.0 and protocol 2026-07-28 only.

## Upload files

Submit PDFs to an authorized Client or Lease:

```sh
lv upload --client 3 lease.pdf amendment.pdf
lv upload --lease 12 amendment.pdf
```

Client Users may submit only to their own active Client and cannot select a Lease. JSON receipts contain accepted file identities and individual rejections; any rejection exits with code 2 while preserving successful receipts. Acceptance means durable submission. Processing continues separately in the application; a receipt does not imply extraction completion or access to Broker progress tools. An uncertain upload response is never automatically resubmitted.

## Download files

Retrieve a Document's sliced PDF, its original, or an Upload original:

```sh
lv download document 45 --output lease.pdf
lv download document 45 --original --output source.pdf
lv download document 45 --lease 12 --revision 7 --output historical.pdf
lv download upload 9 --output submitted.pdf
```

Document downloads resolve their current Lease through the authorized remote `get_document` tool. Explicit `--lease` and optional `--revision` use the selected context's endpoint authorization, including historical Documents that no longer have a current placement. `--revision` requires `--lease`. Default filenames are `document-<id>.pdf` and `upload-<id>.pdf`; `--overwrite` explicitly allows replacing an existing file. Downloads emit JSON containing the saved path after successful completion. Bytes stream directly from signed storage URLs, using a fresh client without credentials or cookies on every redirect. Incomplete transfers leave no finished destination. Rerunning a failed download requests a fresh signed URL from the application; signed URLs are never printed or retained by the CLI.
