dev engine update
Move the runtime engine to another version, installing and pinning it, and write it to the runtime configuration
- Command version
0.0.0- Command configuration
cli:cli.engine.update@0.0.0
Arguments
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
--to | string | No | The engine to move to, as python and a version (for example: python3.12); the one the runtime configuration states where none is given | |
--force,--no-force | boolean | No | false | Install and pin the engine even where it is already the Python detected |
It also takes the global arguments.
Output
It answers with a update.Output.
Examples
dev engine updateInstall and pin the engine the runtime configuration states.
dev engine update --to python3.13Move the runtime to another engine, installing and pinning it and writing it to the runtime configuration.
Errors
| Code | Meaning | Remedy |
|---|---|---|
ENGINE_VERSION_INVALID | The engine version --to names is not one the runtime can be moved to. | Name an engine version as engine show reports one. |
ENGINE_UPDATE_FAILED | Installing the requested engine failed; the message carries the installer's own error. | Repair what the message names and run engine update again. |
PYTHON_VERSION_MISMATCH | The installer finished, but the Python version it was asked for is not the one now active, so the runtime configuration was not changed. | Make the requested version the active one -- the message names both -- and run engine update again. |
Also every code of cli:cli
| Code | Meaning | Remedy |
|---|---|---|
REPO_ROOT_VALIDATION_FAILED | The repository root the run was given, by --repo-root or by the directory it was started in, is not a directory that can be acted on. | Run the command from inside the repository, or pass --repo-root naming its root. |
RUNTIME_CONFIG_FAILED | A runtime configuration file the run reads -- the application's cli.config.yml at one of its scopes -- does not load, or sets an argument default a scope may not set. | Correct the file the message names; config init writes one that loads. |
COMMAND_CONFIG_FAILED | The configuration the command itself is declared by does not load, so the command cannot be run. This is a fault in the application as it was built, not in anything the person running it supplied. | Report it against the application's release, with the message; reinstalling the release with update --force replaces a damaged copy. |
MANIFEST_VALIDATION_FAILED | The command reads the repository's manifest.yml, and none was found at the root, or the one found does not load. | Run the command in a repository that has a manifest, pass --manifest naming one, or correct the manifest where the message says it does not load. |
APP_CONFIG_FAILED | The application's own configuration file in the repository does not load against the type the application declares for it. | Correct the file the message names; config init writes one that loads. |
INPUT_VALIDATION_FAILED | An argument the command line gave is not one the command accepts once it is read -- the wrong type, a value outside its choices, or one a rule on the input refuses. | Give the argument as the command's --help describes it. |
OUTPUT_VALIDATION_FAILED | The command answered with data that does not match the output it declares, so the answer was withheld. This is a fault in the command, not in how it was run. | Report it against the application's release, with the command line that produced it. |
PIPE_STDIN_NOT_PIPED | The command was asked to take its input from stdin, by --from-stdin or by - as a document input's value, and nothing is piped to it -- stdin is a terminal, or there is none. | Pipe in the output of a command run with --response-format json, or give the input another value. |
SECRET_NOT_GIVEN | The command takes a secret input, which is never typed on the command line, and nothing was typed at its prompt or piped to its standard input. | Run the command at a terminal and type the value at the prompt, or pipe it to the command's standard input, one line for each secret it takes. |
SECRET_STDIN_CLAIMED | The command takes a secret input from standard input, and standard input already carries its piped inputs -- --from-stdin, or a document input given - -- so there is nothing to read the secret from. | Run the command at a terminal to be asked for the secret, or give its other inputs on the command line. |
PIPE_STDIN_CLAIMED_TWICE | --from-stdin was given beside a document input given - or -:<path>, so the piped answer would be both the command's inputs and one of them. | Keep one of the two forms. |
PIPE_FIELD_NOT_FOUND | A document input given -:<path> names a field the piped answer does not hold -- a key no mapping on the way has, or an index past the end of a list or into something that is no list -- or the text after -: is no path. | Name a field the command before the pipe answers with, as keys joined by . with [<n>] picking an item from a list, as releases[0].notes. |
ENVELOPE_UNREADABLE | What was piped to the command is not an envelope a command writes, so there is no answer in it to take as input. | Run the command before the pipe with --response-format json, and pipe nothing else between the two. |
PIPE_UPSTREAM_FAILED | The command before the pipe refused, so there is no answer to take as input and this command did not run. Its own errors follow this one in the envelope. | Repair what the errors after this one name, in the command before the pipe, and run the pipeline again. |
PIPE_ANSWER_NOT_INPUTS | --from-stdin takes the piped answer as the command's inputs by name, and the answer is no mapping, or carries a field the command declares no input for. | Pipe in a command whose answer holds only this command's inputs, or give the answer to one document input with - instead. |
UNHANDLED_EXCEPTION | The command failed in a way nothing anticipated, and the message is the failure's own text. | Report it against the application's release, with the command line and the message. |
APPLICATION_RELEASE_NAME_UNKNOWN | The application could not tell which release it is -- the project it was released with, or which of that project's applications it is -- so it cannot look its releases up. | Run the application as it was installed, from the directory toolchain install placed it in, or report it against the release. |
Exit codes
| Code | Meaning |
|---|---|
0 | The command answered; the envelope's status is success and errors is empty. |
1 | The command or the framework refused; the envelope's status is error and errors names each code, with its message. |
2 | The command line could not be read -- an unknown command, a missing or unknown argument -- so nothing ran and no envelope was written; the usage is printed instead. |
Types
update.Output
One of the types update.updated, update.updateFailed, update.invalidRequest.
update.updated
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
statusKind | enum one of updated | Yes | Which answer this is: updated, the requested engine is the Python detected and is written to the runtime configuration | |
requestedVersion | string | Yes | The engine the update moved to, as python and a version in lower case: the one --to named, or the one the runtime configuration states where --to was not given. It is the value written to the runtime configuration as engine | |
activeDetectedBeforeVersion | string | No | The Python found on PATH before the update, as python<major>.<minor>.<patch>; absent where none was found | |
detectedVersion | string | No | The Python found on PATH after the update, as python<major>.<minor>.<patch> | |
executable | string | No | Path of the Python executable detected after the update | |
installed | boolean | Yes | Whether this run installed and pinned Python and synced dependencies; false where the requested version was already the one detected and --force was not given | |
force | boolean | Yes | Whether --force was given | |
updateLog | list[any] | No | [] | One entry per step the update ran, in order -- uv python install, uv python pin, uv sync --group dev -- each with its context, command, exitCode, stdout and stderr; a single update skipped entry where nothing had to be installed |
configPath | string | No | Path of the runtime configuration file the engine was written to |
update.updateFailed
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
statusKind | enum one of update-failed | Yes | Which answer this is: update-failed, a step of the update failed (ENGINE_UPDATE_FAILED) or it finished and the requested version is still not the Python detected (PYTHON_VERSION_MISMATCH). The runtime configuration is left as it was | |
requestedVersion | string | No | The engine the update was moving to, as python and a version in lower case: the one --to named, or the one the runtime configuration states | |
activeDetectedBeforeVersion | string | No | The Python found on PATH before the update, as python<major>.<minor>.<patch>; absent where none was found | |
detectedVersion | string | No | The Python found on PATH when the update ended, as python<major>.<minor>.<patch>: the one found before it where a step failed. Absent where none was found | |
executable | string | No | Path of the Python executable that was detected; absent where none was found | |
installed | boolean | No | Whether the install, pin and sync all ran to their end: false where one of them failed, true where they finished and the requested version was still not the one detected | |
force | boolean | No | Whether --force was given | |
updateLog | list[any] | No | [] | One entry per step the update ran, in order, each with its context, command, exitCode, stdout and stderr; a step that failed is the last, and every step is there where they all ran and the requested version was still not the one detected |
update.invalidRequest
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
statusKind | enum one of invalid-request | Yes | Which answer this is: invalid-request, the engine to move to is no engine version (ENGINE_VERSION_INVALID) and nothing was changed | |
requestedVersion | string | Yes | The engine asked for, as written: the value given to --to, or the one the runtime configuration states |