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 --helpand per-command--help - Version output via
delta versionanddelta --version - OAuth login with Authorization Code + PKCE
- One-shot
127.0.0.1:8400callback server or an optional Console callback handoff - Session storage in
~/.trampoline-ai/delta/auth.jsonwith owner-only permissions - Automatic bearer authentication for service API commands
Requirements
- Python 3.13+
- uv
Installation
From this directory, install the CLI in editable mode:
uv tool install -e .
You can also run the CLI directly during development:
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 ~/.trampoline-ai/delta/auth.json. Delta creates the
containing directory with mode 0700 and writes the credential file atomically with
mode 0600.
Create an OAuth application in the same auth project as ../console:
- Default redirect URI:
http://127.0.0.1:8400/callback - Console callback URI for
--manual-callback:https://cloud.avalanche.run/oauth/callback - Public client: enabled
- PKCE required: enabled
- Scopes:
profile email offline_access user:org:read
A Clerk administrator must register the applicable redirect URI before its login mode can succeed.
The production issuer, public OAuth client ID, and callback port are built in. Sign in without configuration:
delta login
For another deployment, override the public auth configuration explicitly:
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.
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:
delta auth login --no-browser
Use the Console callback when the browser cannot reach the local loopback listener:
delta auth login --manual-callback
Manual callback sign-in requires Delta CLI 0.1.6 or newer. Older CLI releases cannot complete this handoff; upgrade the CLI and start sign-in again if the Console reports that an upgrade is required.
Complete sign-in in the browser, select Copy response at the Console callback page, then paste only that response into Delta's hidden terminal prompt. Never copy, paste, log, or share the raw browser callback URL. The response is bound to the in-memory PKCE sign-in attempt; do not paste it into logs or chat.
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:
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:
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
~/.trampoline-ai/delta/auth.json. An explicit --token wins, then a nonblank
DELTA_TOKEN, then the saved session; 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.
Listing pages
Collection commands accept --limit (default 100, maximum 500) and --cursor.
Human output prints the next continuation; list JSON is now an
{items,next_cursor} envelope. HttpDeploymentApi returns a list-compatible
ApiPage exposing next_cursor; iterating it makes no additional requests.
Live paging continues after the last returned item. Refresh without a cursor to see newer items that sort before that position. Filtered pages may contain no items and still have a continuation.
delta runs artifacts RUN --limit 100 --cursor TOKEN returns one page of nested
artifact files. Its JSON retains the artifact response envelope and adds
next_cursor; bindings and directory values can span pages. delta runs logs
accepts --after-run-sequence and --limit (default/maximum 256). Explicit
--follow remains a polling operation.
Webhook URLs now include organization, project and flow scope:
/v2/hooks/orgs/ORG/projects/PROJECT/flows/FLOW/[CONFIGURED_PATH/]TOKEN.
Use the complete URL returned by the API; opaque-only URLs are removed.
Release files for trampoline-delta 0.1.76
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| trampoline_delta-0.1.76.tar.gz | 192.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| trampoline_delta-0.1.76-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 357.1 kB
Release files / trampoline_delta-0.1.76.tar.gz
| Download URL | trampoline_delta-0.1.76.tar.gz |
|---|---|
| Size | 192.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5fd226f355f646d57b346c185ce63c5166103a1d94b1bae247f1f2961d9ca0b7
|
|
BLAKE2b-256 checksum How to use checksums |
d84e1daf5331131e9258c6e93dedcb717f0cbfc67d6d20b89d794d78d926c9d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / trampoline_delta-0.1.76-py3-none-any.whl
| Download URL | trampoline_delta-0.1.76-py3-none-any.whl |
|---|---|
| Size | 164.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ab382250e57fa3c1f784b924afe5b846473c51c3562e0c288c91077a68c2714
|
|
BLAKE2b-256 checksum How to use checksums |
38cc2916007472737a5d7bdd49328c3a67e7a6e3968c33a6ab3fd55940a961df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
