Metadata-Version: 2.5
Name: trampoline-delta
Version: 0.1.5rc56
Summary: Command line interface for the Delta service
Requires-Python: >=3.13
Requires-Dist: avalanche-ai[runtime]==0.1.0rc2
Requires-Dist: boto3<1.43.1,>=1.42.24
Requires-Dist: botocore<1.43.1,>=1.42.24
Requires-Dist: cryptography>=48.0.1
Requires-Dist: google-auth>=2.38.0
Requires-Dist: google-cloud-storage<4.0.0,>=3.13.0
Requires-Dist: httpx<1.0,>=0.27.0
Requires-Dist: keyring>=25.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-ulid>=3.1.0
Requires-Dist: urllib3<3.0.0,>=2.7.0
Requires-Dist: zstandard>=0.23.0
Description-Content-Type: text/markdown

# Delta CLI

Delta CLI is a command line interface for the Delta service.

This repository contains the Delta command router, version output, and
browser-based CLI authentication.

## Features

- Built-in help via `delta --help` and per-command `--help`
- Version output via `delta version` and `delta --version`
- OAuth login with Authorization Code + PKCE
- One-shot `127.0.0.1:8400` callback server
- Session storage in the OS keychain
- Automatic bearer authentication for service API commands

## Requirements

- Python 3.13+
- uv

## Installation

From this directory, install the CLI in editable mode:

~~~bash
uv tool install -e .
~~~

You can also run the CLI directly during development:

~~~bash
uv run --with-editable . delta --help
uv run --with-editable . delta version
~~~

## Authentication Setup

The CLI uses a public OAuth application. Do not use secret keys for interactive
CLI user login.

The local session is stored in the OS keychain. If keychain access is
unavailable, auth commands fail instead of writing token files.

Create an OAuth application in the same auth project as `../console`:

- Redirect URI: `http://127.0.0.1:8400/callback`
- Public client: enabled
- PKCE required: enabled
- Scopes: `profile email offline_access user:org:read`

The production issuer, public OAuth client ID, and callback port are built in.
Sign in without configuration:

~~~bash
delta login
~~~

For another deployment, override the public auth configuration explicitly:

~~~bash
export DELTA_AUTH_ISSUER_URL="https://your-auth-issuer.example.com"
export DELTA_AUTH_CLIENT_ID="your_oauth_client_id"
~~~

For local development in this monorepo, the CLI can also derive the issuer from
`DELTA_AUTH_PUBLISHABLE_KEY`.

## Command Overview

### `delta version`

Shows the installed Delta CLI version.

### `delta auth login`

Signs in to Delta through your browser.

~~~bash
delta login
~~~

The CLI uses the registered callback port `8400`. Pass `--callback-port 0` for a
random loopback port when another provider supports RFC 8252 loopback redirects.

Use `--no-browser` to print the sign-in URL instead of opening it:

~~~bash
delta auth login --no-browser
~~~

### `delta auth status`

Shows whether you are signed in.

### `delta auth whoami`

Shows the signed-in account.

### `delta auth logout`

Signs out of Delta.

### `delta --help`

Shows available commands and global options.

### Portable Avalanche workspaces

Capture one or more local directories as typed `ava.Workspace` run inputs:

~~~bash
delta runs create demo-flow \
  --workspace source=./input-tree \
  --workspace config=./config-tree
~~~

Each field name must be unique across `--workspace` and JSON inputs. Delta
captures the directory with Avalanche's workspace manifest codec and uploads the
manifest through the run-scoped artifact path; workflow code receives
`ava.Workspace` when its declared input field uses that annotation. Manifests
are limited to 48 MiB; the CLI rejects oversized trees from directory metadata
before reading their file contents.

Materialize terminal workspace trees into a new local directory:

~~~bash
delta runs output run_01KCVST2FP4QC5NKZNN5NS0Z2W --output-dir ./downloaded
~~~

The destination must not already exist. Workspace values are written as
`workspace-0001`, `workspace-0002`, and so on in deterministic result order.
Mixed `ava.File` references remain in the result envelope. Without
`--output-dir`, `runs output` continues to print that standard Avalanche result
document unchanged.

Service API commands automatically load and refresh the signed-in session from
the OS keychain. `--token` and `DELTA_TOKEN` remain explicit automation
overrides; the user TOML configuration rejects plaintext tokens.

The API enforces the selected Clerk organization and its role permissions. The
signed-in user must belong to the requested organization, and that role must
include the Delta action used by the service command.
