CLI (Constellation Lite)

CLI — Constellation Lite

A zero-maintenance CLI proxy. New integration method → new CLI command. Automatically.

CLI Architecture — Request Flow

User

constellation …

→

Typer CLI App

dynamically built

→

Schema cache

~/.constellation/schema.json

→

HTTP proxy client

client.py (httpx)

→

Constellation API

POST /v1/{service}/{method}

→

External API

GitHub, Jira, Slack…

Cache MISS — fetches GET /v1/meta from server, writes schema.json

Cache HIT — reads schema.json directly, no network call at startup

What & Why

The CLI is a zero-maintenance proxy. There is no CLI code to write or maintain when a new integration is added. The lifecycle is:

1. A developer adds a new @service_method-decorated function on the Constellation API server.
2. The server's /v1/meta endpoint immediately includes the new method in its schema.
3. The next time constellation is run, the CLI fetches (or refreshes) the schema and builds a new Typer subcommand for that method automatically.

What you get for free	How
New CLI command	Schema discovery at startup
Correct --flag names	Parameter names from /v1/meta
Correct help text	description field from /v1/meta
Fast startup	1-hour schema cache at ~/.constellation/schema.json
Offline use	Stale cache used with a warning when server is unreachable

No OpenAPI YAML, no CLI glue code, no synchronisation between server and client.

Dynamic Schema Discovery

Schema bootstrap — every CLI invocation

CONSTELLATION_SERVER_URL

env var or config.json

→

GET /v1/meta

schema.py

→

Cache check

~/.constellation/schema.json
1-hour TTL · version tag

→

build_cli_app()

cli.py

→

Typer app ready

one group per service
one cmd per method

Fresh cache — reads schema.json, no HTTP call

Stale or version mismatch — re-fetches /v1/meta, updates schema.json

--refresh flag — forces re-fetch regardless of TTL

Network error + stale cache — warns and continues; hard-fails only if no cache exists

Command Structure

Command tree — built from schema at startup

constellation

↓

github

service group

↓

get-repository --owner --repo
list-repositories --owner
create-issue --owner --repo --title

jira

service group

↓

list-issues --project --status
get-issue --issue-id
create-issue --project --summary

slack

service group

↓

send-message --channel --text
list-channels
get-channel --channel-id

Parameter names are taken directly from the schema — snake_case becomes --kebab-case flags.
All commands accept --format (text · json · agent) and --tenant.

Reference

Installation

pip install constellation-lite

Configuration

The CLI resolves the server URL in priority order:

1. CONSTELLATION_SERVER_URL environment variable
2. server_url key in ~/.constellation/config.json

# Option A — environment variable
export CONSTELLATION_SERVER_URL=http://localhost:3007

# Option B — config file
mkdir -p ~/.constellation
echo '{"server_url": "http://localhost:3007"}' > ~/.constellation/config.json

Environment variables

Variable	Required	Description
CONSTELLATION_SERVER_URL	Yes (or config file)	Base URL of the Constellation API server
CONSTELLATION_API_KEY	No	Forwarded as X-API-KEY header on every request

Schema cache

Path	~/.constellation/schema.json
TTL	1 hour (wall-clock since fetched_at)
Invalidation	Server version change or --refresh flag
Offline behaviour	Stale cache used with a warning; hard-fail only if no cache exists

Global flags

All commands accept these flags in addition to their own parameters:

Flag	Values	Default	Description
--format	text, json, agent	text	Output format
--output	file path	—	Write output to file instead of stdout
--tenant	string	—	Tenant ID forwarded as X-Tenant-ID header
--refresh	—	—	Force schema re-fetch, ignoring cache TTL

Example session

# 1. List all GitHub repositories for an org
constellation github list-repositories --owner myorg

# 2. Get a specific repository
constellation github get-repository --owner myorg --repo myrepo

# 3. List open Jira issues in a project
constellation jira list-issues --project PROJ --status "In Progress"

# 4. Send a Slack message and capture the response as JSON
constellation slack send-message --channel general --text "Deployment complete" --format json

# 5. Explore all available services and commands
constellation --help
constellation github --help

# 6. Force schema refresh (e.g. after server upgrade)
constellation --refresh github list-repositories --owner myorg

Key source files

File	Role
apps/constellation-lite/constellation_lite/cli.py	Entry point; builds the Typer app dynamically from schema
apps/constellation-lite/constellation_lite/schema.py	Fetches /v1/meta; manages 1-hour TTL cache
apps/constellation-lite/constellation_lite/client.py	httpx-based proxy; issues POST /v1/{service}/{method}
apps/constellation-lite/constellation_lite/config.py	Resolves CONSTELLATION_SERVER_URL from env or ~/.constellation/config.json