lammy 0.1.0

Add your description here

lammy

lammy is a minimal command line helper for day-to-day Lambda Cloud management. It focuses on the flow of picking an instance type, launching it, wiring up SSH, then shutting it down when you are done.

uv run lammy --help

Quick Start

1. Install dependencies

   uv sync
   

2. Authenticate

   uv run lammy auth login
   

   Paste your Lambda API key when prompted. You can generate keys in the Lambda Cloud dashboard. lammy also discovers LAMBDA_API_KEY from the environment or a local .env.

3. Set your defaults (optional but recommended)

   uv run lammy settings set --region us-west-1 --ssh-key my-default-key
   

4. Pick a machine

   uv run lammy list
   

   This prints the instance types that currently have capacity. Add --all if you want the full catalog.

5. Launch, connect, terminate

   uv run lammy up              # guided launch flow (press enter to accept defaults)
   uv run lammy ssh             # jumps straight into SSH for the most recent instance
   uv run lammy down            # terminates the most recent instance (with confirm)
   

   lammy up writes an SSH host entry automatically. Use the printed alias in your Remote Explorer / editor of choice if you prefer a GUI connection.

Commands

Authentication

Command	Description
lammy auth login	Prompt for an API key and store it in ~/.config/lammy/config.json.
lammy auth show	Display the masked API key currently in use and the config path.

Everyday flow

Command	Description
lammy list	Show instance types with live capacity (--running flips to currently running servers, --all includes types without capacity).
lammy up	Guided launcher. Prompts for type/region/SSH key if not already configured, auto-picks the GPU Base 24.04 image when available, waits for the public IP, and writes your SSH config.
lammy ssh [name]	Connect to the most recent instance (or a named one). Any extra arguments (e.g. -L ...) are passed through to ssh.
lammy down [name]	Terminate the most recent (or a named) instance. Use --force to skip the confirm.

Advanced catalog commands

Command	Description
lammy types	Same as lammy list, but sticks to instance types only.
lammy types --all	Include types with no reported capacity.

Instances

Command	Description
lammy instances list	Show running instances, with region, pricing, and status.
lammy instances launch ...	Launch a new VM. Honors defaults from lammy settings and accepts overrides (--instance-type, --region, --ssh-key, --image, --user-data). By default the CLI writes an SSH Host entry once the instance has a public IP.
lammy instances restart <id-or-name>...	Restart one or more instances.
lammy instances terminate <id-or-name>...	Terminate instances (with optional --yes to skip confirmation).

SSH helpers

Command	Description
lammy ssh setup <id-or-name>	Write/update a dedicated host block in ~/.ssh/config.
lammy ssh connect [id-or-name]	Same as the bare lammy ssh command, but lets you spell out an identifier/alias and optional extra args.
lammy ssh keys	List SSH keys registered with Lambda Cloud.

Settings

lammy settings stores lightweight defaults inside ~/.config/lammy/config.json. The values are:

Key	Purpose
default_region	Region used when --region is omitted on instances launch.
default_ssh_key_name	SSH key name assumed when --ssh-key flags are omitted.
default_image	Image string applied on launch (family:gpu-base-24-04 by default).
ssh_user	Default user used in generated SSH host blocks and ad-hoc connections.
ssh_identity_file	Optional path to an identity file (~/.ssh/id_ed25519, etc.) written into the SSH config.
ssh_alias_prefix	Prefix applied to generated host aliases (default lammy).

Inspect the stored configuration with:

uv run lammy settings show

Images

lammy pins launches to the gpu-base-24-04 family out of the box. Change it whenever you like:

uv run lammy settings set --image family:<family-name>

Prefer an explicit image ID? Use --image id:<uuid>.

API coverage

The CLI uses the Lambda Cloud REST 1.8.3 API. The OpenAPI definition is bundled in spec.json if you want to explore the endpoints yourself.

Publishing

The project is built with uv. To publish to PyPI:

uv build
uv publish --token <your-pypi-token>

Remember to update pyproject.toml metadata (description, version, classifiers) before publishing. When testing, you can target TestPyPI by setting UV_PYPI_URL=https://test.pypi.org/simple.