Summary
Add a flag to kosli snapshot <type> that creates the target environment on the
fly if it does not already exist, instead of failing. This lets users report a
snapshot in a single command rather than requiring a prior kosli create environment.
Optional flags allow the auto-created environment's description and scaling
behavior to be configured inline.
Motivation
Today, reporting a snapshot to an environment that hasn't been created yet fails,
because kosli snapshot assumes the environment already exists. This forces a
two-step setup:
kosli create environment prod --type docker --description "..."
kosli snapshot docker prod --api-token <token> --org <org>
This is extra friction during onboarding - workflows that report snapshots must special-case the "first run" where the environment doesn't exist yet, or run a separate create step guarded by error handling. There is also a scaling scanario where we want to define mapping and start reporting.
Proposed solution
Add a boolean flag to the kosli snapshot command group, plus optional
pass-through flags for environment configuration:
kosli snapshot docker prod \
--auto-environment \
--environment-description "Production docker host" \
--include-scaling \
--api-token <token> \
--org <org>
The flag is --auto-environment (short -a), with --auto-env accepted as an
alias.
Behavior:
- If the environment named
prod does not exist, create it before reporting the
snapshot.
- Infer
--type from the snapshot subcommand (snapshot docker → docker,
snapshot k8s → k8s, etc.), so the type never has to be restated.
- If the environment already exists,
--auto-environment is a no-op and the
snapshot is reported as normal (idempotent).
Optional flags (only take effect when an environment is actually created):
--environment-description <string> — description for the new environment.
Defaults to something like "Auto-created by kosli snapshot" if omitted.
--include-scaling / --exclude-scaling — control whether scaling events
(changes in the number of running instances) produce new snapshots, mirroring
the existing flags on kosli create environment. If neither is passed, the
environment inherits the platform default (scaling events excluded).
Edge cases / considerations
- Optional flags without
--auto-environment — if the user passes
--environment-description or the scaling flags but the environment already
exists (or --auto-environment isn't set), decide between: silently
ignoring them, warning, or erroring. Recommend a warning so a stale
description flag doesn't fail an otherwise-valid snapshot.
- Logical environments cannot receive snapshots, so auto-create should only
ever create a physical environment of the subcommand's type. A snapshot
targeting an existing logical env should still error clearly.
- Type mismatch — if the environment already exists with a different type
than the subcommand, fail with a clear message rather than silently reporting.
- Conflicting scaling flags — passing both
--include-scaling and
--exclude-scaling should error, consistent with kosli create environment.
- Short flag
-a — confirm -a isn't already bound on any kosli snapshot
subcommand before reserving it globally across the group.
Acceptance criteria
Summary
Add a flag to
kosli snapshot <type>that creates the target environment on thefly if it does not already exist, instead of failing. This lets users report a
snapshot in a single command rather than requiring a prior
kosli create environment.Optional flags allow the auto-created environment's description and scaling
behavior to be configured inline.
Motivation
Today, reporting a snapshot to an environment that hasn't been created yet fails,
because
kosli snapshotassumes the environment already exists. This forces atwo-step setup:
This is extra friction during onboarding - workflows that report snapshots must special-case the "first run" where the environment doesn't exist yet, or run a separate create step guarded by error handling. There is also a scaling scanario where we want to define mapping and start reporting.
Proposed solution
Add a boolean flag to the
kosli snapshotcommand group, plus optionalpass-through flags for environment configuration:
The flag is
--auto-environment(short-a), with--auto-envaccepted as analias.
Behavior:
proddoes not exist, create it before reporting thesnapshot.
--typefrom the snapshot subcommand (snapshot docker→docker,snapshot k8s→k8s, etc.), so the type never has to be restated.--auto-environmentis a no-op and thesnapshot is reported as normal (idempotent).
Optional flags (only take effect when an environment is actually created):
--environment-description <string>— description for the new environment.Defaults to something like
"Auto-created by kosli snapshot"if omitted.--include-scaling/--exclude-scaling— control whether scaling events(changes in the number of running instances) produce new snapshots, mirroring
the existing flags on
kosli create environment. If neither is passed, theenvironment inherits the platform default (scaling events excluded).
Edge cases / considerations
--auto-environment— if the user passes--environment-descriptionor the scaling flags but the environment alreadyexists (or
--auto-environmentisn't set), decide between: silentlyignoring them, warning, or erroring. Recommend a warning so a stale
description flag doesn't fail an otherwise-valid snapshot.
ever create a physical environment of the subcommand's type. A snapshot
targeting an existing logical env should still error clearly.
than the subcommand, fail with a clear message rather than silently reporting.
--include-scalingand--exclude-scalingshould error, consistent withkosli create environment.-a— confirm-aisn't already bound on anykosli snapshotsubcommand before reserving it globally across the group.
Acceptance criteria
kosli snapshot <type> <name> --auto-environment(or-a) creates<name>with the inferred type when it doesn't exist, then reports thesnapshot.
--auto-envworks as an alias for--auto-environment.--typerequired.--environment-descriptionsets the description on the auto-created env;a sensible default is used when omitted.
--include-scaling/--exclude-scalingset scaling behavior on theauto-created env and error when used together.
kosli snapshot <type>subcommands.kosli snapshotand the getting-started/CI tutorials.