Commands by group

All commands accept --json and -p <path>. Add -h to any of them for its full help.

Creating the project

aseptic init [path]                 # .aseptic/ with its config and an empty catalog

Everything else needs a project —the folder that contains .aseptic/—. On the desktop the installer seeds it the first time; from a terminal (a CI, a fresh clone) you create it with this. It overwrites nothing: on a half-made folder it completes what’s missing.

Scenario status and lifecycle

aseptic status                      # live engine, Docker, active scenario and micros
aseptic doctor [scenario]           # environment check before launching (and how to get what's missing)
aseptic start <scenario> [flags]    # starts (launches daemon if needed) and waits healthy
aseptic stop                        # stops the active scenario
aseptic restart <micro>             # restarts a single micro
aseptic debug <micro> [on|off]      # opens or closes its debugger; without on/off, how to attach
aseptic runs [show|logs|pin|delete] # scenario run history
aseptic restart-all                 # stops and starts the whole scenario again
aseptic metrics [micro]             # last metrics sample (--json = history)
aseptic set-resolution <dep> <local|cloud|mock>   # changes the resolution hot
aseptic cleanup [scenario]          # defensive cleanup (orphans, ports)
aseptic prep <scenario> --when <pre-boot|post-migrate>
aseptic console <service>           # psql/redis-cli inside its container
aseptic kafka topics|consume|produce   # topics and messages of the infra Kafka
aseptic logs [micro] [-f] [-n N] [--errors] [-g pattern]
aseptic call <micro> [path] [-X method] [-d body] [-H k=v...]
aseptic diagnose <micro> [-n N]     # what's wrong with a micro, in one shot

Flags for start: -r/--resolve <dep=mode> (one-off resolution override), -m/--mode <micro=mode> (native|container), --no-wait, --no-docker, --timeout <s> (default 600). start starts Docker on its own unless --no-docker.

Scenarios

aseptic scenario list | show <n> | graph <n> | save --file <yml> | delete <n>
aseptic scenario add-service <scenario> <micro>      # without resending the whole document
aseptic scenario remove-service <scenario> <micro>
aseptic scenario set-resolution <scenario> <dep> <local|cloud|mock>   # sets the stored one
aseptic scenario from-folder <folder> <name>          # imports the folder and creates the scenario
aseptic scenario export <n> [-o file] [--include-run]
aseptic scenario import <file> [--apply] [policies]

add-service and remove-service edit what’s saved: there’s no need to resend the whole scenario to touch one micro. And mind the two set-resolution: the top-level one (aseptic set-resolution) changes the resolution hot, on the running scenario; this one pins it in the saved scenario.

from-folder is the getting-started shortcut: it imports every micro in a folder and creates the scenario with them, in one go.

Micros

aseptic service list | show <id> | add <repo-path> | save --file <yml> | delete <id>
aseptic service detect <path>       # which manifest Aseptic sees there, WITHOUT saving it
aseptic service clone <url> [--alta]            # clones and, with --alta, registers it
aseptic service clone-all <url...>  # clones in bulk and autodetects each micro
aseptic service import-all <folder>             # registers every micro in a folder
aseptic service export <id> [--include-run] | import <yml...>
aseptic service drift <id>          # does the manifest diverge from the repo? (exit 1 if drift)
aseptic service rescan <id>         # reconciles from the repo (preserves curation)
aseptic service rescan-all          # the same for the WHOLE catalog
aseptic service effective-config <id>           # final value of each key and which layer it comes from
aseptic service frontend-info <id>  # front: how it serves, whether it takes --proxy-config and what the repo has
aseptic service branch <id> | branches <id> | checkout <id> <branch> | fetch <id> | pull <id>
aseptic service fetch-all           # fetches news for EVERY repo in the catalog
aseptic service switch-branch <id> <branch>     # switches branch and reconciles the manifest
aseptic service hot-switch-branch <id> <branch> # the same with the micro running: stops only that one
aseptic dependency rename <from> <to>  # renames the dependency across services, scenarios and mocks
aseptic service files <id> [pattern] [-d <subfolder>]   # lists files in the micro's repo
aseptic service read-file <id> <path>                   # prints a text file from the repo
aseptic service write-file <id> <path> [--from <file>]  # writes one (or from standard input)

clone-all and import-all onboard a whole team: cloning twenty repos and registering them one by one is the afternoon this saves on day one.

effective-config answers “where does this value come from?” without starting anything, which is the question behind every micro that starts with the wrong configuration.

Databases

aseptic db list | save --file <yml> | delete <id>
aseptic db test <host> <port>       # TCP reachability (exit 1 if no response)

Mocks

aseptic mock services | catalog [service] | calls | events | clear-calls
aseptic mock save <service> --file <json> | delete <service> --method GET --path /x
aseptic mock set-active <service> --method GET --path /x --variant 1
aseptic mock capture|uncapture <service> --method GET --path /x   # calls the real service and records the response
aseptic mock operations <service> | skeleton <service> <method> <path>
aseptic mock set-openapi <service> [source]     # where the bodies come from (no source removes it)
aseptic mock set-service <group> --prefix /x [--openapi <source>] [--base-url <url>] [--rename-from <id>]
aseptic mock regroup <group> [--from <service>]    # moves into the group the stubs under its prefix
aseptic mock delete-service <service> --yes     # deletes the service's WHOLE mock catalog
aseptic mock from-call <method> <path>
aseptic mock probe <method> <path> [-H 'Name: value'] [-d '<body>']  # what it would serve, and by which rule
aseptic mock put-file <service> <file>  # copies a file to mocks/files/ to serve it as a body
aseptic mock export|import <service> [file] | export-all|import-all [file]
aseptic mock request [path] [-X method] [-d body] [-H k=v]   # calls the mock gateway (live engine)

In capture, an endpoint stops serving its variant: it calls the real service and saves the response as a Real <status> variant, which becomes active. Once you turn it off (uncapture) it keeps serving what it recorded.

Custom startup

aseptic run show <id> | set <id> [options] | clear <id> | preview <id>
aseptic run export <id> [-o file] | import <id> <file>

run set accepts --profile, --prop k=v, --toggle <id>, --extra-args, --command, --datasource-ref <id>, --datasource local|cloud|custom [--url ...] and --tools auto|local|container.

--tools decides where the native startup’s tools come from: auto (the default) uses your machine’s and, if one is missing and Docker is running, the tools container; local and container pin it, and auto drops the micro’s setting. See Native vs container mode.

Settings

aseptic config show | get <key> | set <key> <value> | unset <key>

Keys: workspace, composeFile (bundled or path), mockPort, caBundle (your company’s CA, PEM or DER), toolchainRegistry (mirror prefix for the tools images) and credentials.<name>.

Development tools

aseptic toolchain list                   # what it can install and what's installed
aseptic toolchain install java 21        # for java, the major version
aseptic toolchain install node 22.22.3   # for the rest, the exact one (or a prefix: 22)
aseptic toolchain remove maven 3.10.0    # deletes it from Aseptic's cache

It installs the missing JDK, Maven, Gradle, Node, Go or .NET SDK in Aseptic’s cache (~/.aseptic/toolchains/): no administrator, without touching the machine’s PATH, and verifying the checksum before extracting. The one you already have installed still wins. aseptic doctor tells you what’s missing and which command gets it.

Docker, catalog bundle and daemon

aseptic docker status | start [--no-wait] [--timeout <s>]
aseptic containers | docker-clean | infra <n> | infra-up <n> | infra-down
aseptic bundle export [-o file] | import <file> [--overwrite]
aseptic daemon start | stop | status

aseptic telemetry info | on | off | dismiss | test [--note <text>]
aseptic telemetry report <message> # REAL incident report (grouped as an issue)
aseptic report <message> [-n N]     # LOCAL report in .aseptic/.runtime/reports/
aseptic consent info | history | accept --yes | sync
aseptic access sync                 # sends pending sign-ins to the account history
aseptic info                        # version, effective paths and active scenario
aseptic ops [--json]                # the engine's complete surface
aseptic mcp                         # starts the MCP server over stdio

The two reports are not the same one. telemetry report sends yours, so it needs telemetry on and a network; report writes a file on your disk, works without either and gives you its path so you can attach it wherever you want. Both are scrubbed.

Local libraries

aseptic library list | show <id> | add <path> | delete <id>
aseptic library clone <url>         # clones the repo and returns its path
aseptic library detect <path>       # which library Aseptic sees there
aseptic library build <id>          # runs its build command
aseptic library link <id>           # builds and puts the artifact where the consumer sees it
aseptic library unlink <id>         # removes the link in every consumer
aseptic library watch <id> | unwatch <id>       # rebuild and relink on change (opt-in)
aseptic library status [id]         # resolved consumers and whether it's linked (no id: all of them)
aseptic library branch <id> | branches <id> | checkout <id> <branch> | fetch <id> | pull <id>

watch is opt-in on purpose: rebuilding on every change costs, and it isn’t always what you want while you’re working on the library. See Libraries.

Team catalog

aseptic team list                   # what the team shares
aseptic team status                 # is what's here still what the team shares?
aseptic team adopt <id> [--apply]   # bring it over and adopt it here
aseptic team fetch <id> [-o file]   # download the bundle only
aseptic team publish <scenario> [-d "what it's for"]
aseptic team unpublish <id> --yes   # removes it for the WHOLE team

Without --apply, adopt only shows the plan and what’s missing on this machine. It needs the project to have a catalog configured. See Team.

Account, plan and personal settings

aseptic plan                        # plan, status, period and seats
aseptic sync status                 # published revision vs. the one this copy knows
aseptic sync pull | push            # bring in or publish your personal settings
aseptic sync key-create | key-set <key>         # the key that encrypts them
aseptic sync forget                 # stop syncing and delete what was published

Buying is not in the CLI on purpose: it happens in the web portal or from Settings. What sync syncs are your settings (theme, palette, layout, language), never anything from the project.

Tasks, dependencies and MCP surface

aseptic tasks                       # the engine's long-running tasks
aseptic tasks --history             # the latest finished ones, with their result
aseptic tasks --output <id>         # the output of one, already sanitized
aseptic install <micro>             # installs a Node/Angular micro's dependencies
aseptic logs-export [-o file]       # diagnostics bundle, already scrubbed
aseptic mcp-surface                 # which MCP surface is active
aseptic mcp-usage                   # how it's being used on this machine
aseptic mcp-tune                    # what's failing in that surface, with evidence

The logs-export bundle is scrubbed: declared credentials don’t travel in it, which is exactly what it’s attached to a bug report for.