lagotto command reference

lagotto watches for EC2 capacity and acts when it appears — notify, hold, or launch via spawn — and can maintain goal-driven fleets. This is the exhaustive command and flag reference. For an overview see the lagotto guide.

Generated reference

This page is generated from the lagotto CLI itself and kept in sync by a release-gated drift check, so every command and flag below matches the shipped binary. For task-oriented walkthroughs see the guides.

Global flags

These apply to every lagotto command.

Flag	Short	Type	Default	Description
--accessibility		bool		Enable accessibility mode (implies --no-emoji)
--account		string		Expected AWS account ID (optional guard)
--history-table		string	lagotto-match-history	DynamoDB table name for match history
--lang		string		Language for output (en, es, fr, de, ja, pt)
--no-emoji		bool		Disable emoji in output
--output	-o	string	table	Output format (table, json)
--profile		string		AWS named profile (overrides SPORE_PROFILE/AWS_PROFILE and the shared config)
--region		string		Default AWS region (overrides SPORE_REGION/AWS_REGION and the shared config)
--verbose	-v	bool		Enable verbose output
--watches-table		string	lagotto-watches	DynamoDB table name for watches

lagotto cancel

Cancel an active watch

lagotto cancel <watch-id> [flags]

Flags:

Flag	Short	Type	Default	Description
--yes	-y	bool		Skip the confirmation prompt

lagotto deploy

Stand up lagotto's hosted capacity poller (DynamoDB, SNS, Lambda, EventBridge Scheduler) in your OWN AWS account, so watches are serviced server-side — armed once, then hands-off — instead of depending on a foreground 'poll --daemon' that dies when your laptop sleeps.

It downloads the published capacity-poller Lambda artifact for the given --version, uploads it to a bucket in your account, and deploys the embedded CloudFormation stack. The poller schedule deploys DISABLED; the first 'lagotto watch' enables it (and the poller self-disables when no active watches remain).

Use --teardown to delete the stack.

lagotto deploy [flags]

Flags:

Flag	Short	Type	Default	Description
--environment		string	production	Environment tag (production, staging, development)
--lambda-bucket		string		S3 bucket for the Lambda artifact (default: lagotto-lambda-<account>-<region>, created if absent)
--region		string		AWS region (default: from your AWS config)
--stack-name		string	lagotto	CloudFormation stack name
--teardown		bool		Delete the stack instead of deploying it
--version		string	dev	lagotto release version to pull the poller Lambda from
--yes	-y	bool		Skip the confirmation prompt

lagotto extend

Extend a watch's TTL

lagotto extend <watch-id> [flags]

Flags:

Flag	Short	Type	Default	Description
--ttl		string	24h	New TTL from now (e.g., 24h, 7d)

lagotto history

Show match history

lagotto history [flags]

Flags:

Flag	Short	Type	Default	Description
--watch-id		string		Filter by watch ID

lagotto launch

Schedule an instance launch to fire at a clock time (--at), after a delay (--after), or on a recurring cron (--cron) — as opposed to 'watch', which fires when capacity appears. The motivating case is launching into an EC2 Capacity Block at its reserved start time:

lagotto launch --at 2026-07-01T08:00:00Z --spawn-config block.yaml

where block.yaml sets reservation_id + capacity_block.

This is driven by EventBridge Scheduler in the hosted poller stack, so it requires 'lagotto deploy' to have been run (the schedule targets the poller Lambda in your account). The launched instance always carries a TTL (#38).

lagotto launch [flags]

Flags:

Flag	Short	Type	Default	Description
--after		string		Fire once after this delay (e.g. 6h, 30m, 2d)
--at-reservation-start		bool		Fire at the reservation's start time (derived from the reservation), retrying through the window open until the instance runs (requires --reservation-id)
--at		string		Fire once at this RFC3339 time (e.g. 2026-07-01T08:00:00Z)
--az		string		Availability zone (required to match a Capacity Block's AZ)
--cron		string		Fire on this cron schedule (e.g. '0 9 ? * MON-FRI *')
--fire-early		duration	2m0s	With --at-reservation-start: fire this long before the window open so a Scheduler delay doesn't burn paid time
--if-exists		string		If an instance with this Name already exists at fire time: skip|launch|replace (default: skip for --at/--after, launch for --cron)
--name		string		Instance Name tag (the overlap dedup key); defaults to the spawn config's name
--region		string		AWS region to launch in (default: from your AWS config)
--reservation-id		string		Capacity Block reservation id (cr-…) to launch into
--retry-interval		duration	30s	With --at-reservation-start: how often to retry through the boundary until the launch succeeds
--spawn-config		string		YAML file with the spawn LaunchConfig (required)
--stack-name		string	lagotto	Deployed lagotto stack name (provides the poller target)

lagotto list

List your watches

lagotto list [flags]

Flags:

Flag	Short	Type	Default	Description
--all		bool		Show all statuses (default: active only)

lagotto poll

Manually trigger a single poll of all active watches. This is for local testing; in production, polling runs on a Lambda schedule.

lagotto poll [flags]

Flags:

Flag	Short	Type	Default	Description
--daemon		bool		Loop in the foreground, polling on --interval, until no active watches remain
--interval		duration	5m0s	Polling interval in --daemon mode (e.g. 30s, 5m)
--mine		bool		Only poll watches created by the calling identity
--no-lease		bool		Disable the per-watch processing lease (not recommended when multiple pollers run)
--project		string		Only poll watches with this project label (default: $LAGOTTO_PROJECT)
--watch		stringSlice		Only poll these watch IDs (comma-separated or repeated)

lagotto setup

Provision lagotto's backend: the DynamoDB tables it uses to store watches and match history (lagotto-watches and lagotto-match-history by default; override with --watches-table / --history-table), and — if the hosted poller has been deployed ('lagotto deploy') — the runtime IAM policy that lets the poller spawn/hold/submit.

The table creation is idempotent (existing tables are left untouched) and normally automatic: 'lagotto watch' creates the tables on first use. Run 'setup' explicitly to provision the backend ahead of time, or — importantly — after 'lagotto deploy' to grant the poller its permissions. 'deploy' creates only a minimal execution role (so the runtime Lambda can never self-escalate); 'setup', run by you, attaches the spawn/hold/SageMaker/scheduler policy. Until then the poller can only notify. If the poller role doesn't exist yet, setup creates the tables and prints a next-step note instead of failing.

lagotto setup

lagotto status

Show details of a watch

lagotto status <watch-id>

lagotto teardown

Delete the DynamoDB tables lagotto uses (lagotto-watches and lagotto-match-history by default).

lagotto already tears these down automatically once there are no active watches and the tables have drained (watches and match history age out via DynamoDB TTL). Use this to remove them explicitly.

By default it refuses to delete tables that still hold records, so you don't lose match history; pass --force to delete regardless.

lagotto teardown [flags]

Flags:

Flag	Short	Type	Default	Description
--force		bool		Delete even if the tables still contain records

lagotto version

Display version, build date, and git commit information for lagotto.

lagotto version

lagotto watch

Watch for EC2 instance availability across regions and AZs.

The pattern supports wildcards: "p5.*" matches all p5 sizes, "g5.xlarge" is exact. When capacity is found matching your criteria, the configured action is taken.

lagotto watch <instance-type-pattern> [flags]

Flags:

Flag	Short	Type	Default	Description
--action		string	notify	Action on match: notify, spawn, hold
--azs		stringSlice		Availability zones to pin/order within the region(s), comma-separated (e.g. us-west-2b,us-west-2c). Empty = all AZs. AZ breadth is free (same-region data locality), so all AZs are tried each poll.
--maintain		int		Goal-driven fleet: maintain this many workers (relaunching toward the goal, even from zero) until --until holds. Requires --action spawn. 0 = single-shot (default).
--max-price		float64		Maximum acceptable price per hour (0 = any)
--notify		stringSlice		Notification channels (e.g., email:user@example.com, webhook:https://...)
--project		string		Project label for scoping a local 'poll --daemon --project' in a shared account (default: $LAGOTTO_PROJECT)
--regions	-r	stringSlice		Regions to watch (comma-separated; empty = all enabled). Widening across regions can break data co-location (cross-region egress) — prefer --azs within your data's region first.
--sagemaker-config		string		YAML/JSON file with the SageMaker job definition (required for --service sagemaker)
--service		string	ec2	Capacity service: ec2, or sagemaker (submits your SageMaker job for ml.* types)
--spawn-config		string		YAML file with spawn LaunchConfig (required for --action spawn)
--spot		bool		Watch for Spot capacity (default: On-Demand)
--ttl		string	24h	How long to keep watching (e.g., 24h, 7d)
--until		string		Fleet completion condition, re-checked each poll: 's3-empty: s3://b/manifest minus s3://b/done/', 'http-200: https://…', or 'shell: <cmd>' (shell = local daemon only). When true the fleet retires.