systemslab submit

Description	Submit an experiment to be run by SystemsLab
Usage	systemslab submit [OPTIONS] <SPEC>

Description

The systemslab submit command submits a new experiment to be run by the requested SystemsLab server. The experiment is specified by an experiment specification file.

Experiment Specification

The experiment specification file describes the steps that will be taken to perform the experiment: what jobs are run, what steps each of them runs, and where they can be scheduled. The experiment specification can be written in json, yaml, or jsonnet. Which one is loaded will depend on the extension of the provided file. If the path does not have an extension then yaml will be assumed.

See the experiment specification reference for documentation of the JSON object that the experiment specification file should expand to.

Budget checks

--budget <usd> runs a client-side cost check before submitting, for deployments running the AWS infrastructure manager. It calls the same estimator as systemslab infra estimate and prints the exact same breakdown to stderr (not stdout — submit prints only the experiment id to stdout, so ID=$(systemslab submit ...) scripts see just the id, with or without --budget), then compares the on-demand high figure — never the spot price, and never the low end of a range — against --budget.

• Under budget: the submission proceeds, and stderr says so.
• Under budget, but one or more named --instance-type candidates have no price at all: the submission still proceeds, but the pass is qualified — stderr says the figure only covers the priced candidates and names how many were not priced. The high figure is a floor, not a ceiling, when part of the fleet is unpriced, so an unqualified "within budget" would overclaim.
• Over budget: the submission is refused, unless --yes is given, in which case it proceeds and prints a visible warning explaining why.
• Unknown estimate (no pricing data for any priced candidate, or no completed run history for this experiment name): there is nothing to compare --budget against, so this refuses too, for the same reason and with the same --yes override — an unverifiable budget is never treated as a passed check.

--budget requires --host-count (a plain submission has no host count of its own to price); --instance-type and --region are optional, matching systemslab infra estimate.

This is a client-side courtesy, not an enforced spending cap. SystemsLab does not track or enforce budgets anywhere else — nothing stops the same submission from going through the REST/MCP/GraphQL APIs directly.

--budget is not supported when submitting a TOML matrix of more than one variant.

systemslab submit my-benchmark.jsonnet --budget 50 --host-count 4 --instance-type m5.large

Options

Option	Default	Description
-n, --name		The name of this experiment.
--tail		Wait for the experiment to complete and its log messages in the meantime.
-p, --param		Pass a parameter to use when evaluating the experiment specification. If --context is specified, then the parameter value will also be recorded within the context.
--context		Attach this experiment to the provided context.
--jpath		Add an extra include path to use when resolving jsonnet imports.
--jsonnet-max-stack	200	Limit the recursion depth that the jsonnet vm is allowed to reach when evaluating jsonnet files.
--priority		Scheduling priority for this experiment. Overrides the priority field in the experiment spec. Higher values are scheduled before lower values.
-q, --quiet		Silence progress bars when submitting matrix variants.
--budget		Refuse to submit if the estimated on-demand cost exceeds this many US dollars, unless --yes overrides. See Budget checks above. Requires --host-count.
--host-count		How many hosts to price when checking --budget. Required together with --budget; has no effect without it.
--instance-type		Candidate instance type(s) to price when checking --budget. Can be provided multiple times. Omit to price against every instance type this deployment has ever priced in --region. Has no effect without --budget.
--region		The AWS region to price when checking --budget. Defaults to this deployment's configured infrastructure region. Has no effect without --budget.
--yes		Submit even if --budget is exceeded, or if the estimate needed to check it is unknown. Has no effect without --budget.

Common Options

Option	Default	Description
--systemslab-url		The URL at which to access the systemslab server.
--color	auto	Controls when color is used in the output. Possible values are auto, always, and never.
--output-format	long	Output format to use when outputting messages. long will result output designed to be human-readable while short is short output meant to be used within scripts.

Environment Variables

Variable	Description
SYSTEMSLAB_URL	Specify the URL used to contact the SystemsLab server. Equivalent to --systemslab-url.