pkgmgr update
Move this application to its newest release, or to the one --to names -- for an application the toolchain installed, which fetches the public release built for this machine, checks it and puts it in place, showing the download and then what the release changed; a release older than the one installed is refused without --force; refused for an application run from its source or started from outside the install directory
- Command version
0.0.0- Command configuration
cli:cli.update@0.0.0
Arguments
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
--to | version | No | The release to move to, written major.minor.patch: one of the versions version list shows. Left out, the newest. The same version as the one installed changes nothing, and an older one is refused unless --force is given | |
--force,--no-force | boolean | No | false | Permit moving backwards, to a release older than the one installed, and nothing else: a release the store does not hold, an application nothing installed and a file that fails its digest are refused with it as without |
It also takes the global arguments.
Output
It answers with a update.update.
Examples
pkgmgr updateMove the installed application to its newest release.
pkgmgr update --to 1.2.0Move it to one release, as version list names them.
pkgmgr update --to 1.1.0 --forceMove it back to an older release.
Errors
| Code | Meaning | Remedy |
|---|---|---|
UPDATE_RUN_FROM_SOURCE | The application is running from its source checkout rather than from an installed release, so there is no release for update to replace. | Bring the checkout up to date with git instead, and point the executable at it with install. |
UPDATE_NOT_INSTALLED | This executable was started from outside the directory the toolchain installs applications into, so nothing installed it and there is no installed release to replace. | Install the application with toolchain install <application> and run it from there. |
UPDATE_VERSION_NOT_HELD | The catalog holds no release of the version --to names for this machine's platform. | Name one of the versions version list shows, or leave --to out for the newest. |
UPDATE_DOWNGRADE_REFUSED | The version --to names is older than the one installed, and update moves backwards only when told to. | Add --force to install the older release anyway. |
UPDATE_VERSION_NOT_A_RELEASE | The version --to names carries a suffix, which marks a version still being changed; no release carries one. | Name one of the versions version list shows, without a suffix. |
Also every code of toolchain:toolchain-release
| Code | Meaning | Remedy |
|---|---|---|
APPLICATION_NAME_INVALID | The text given does not name an application as one is written. | Write the application's name, such as dev-tool, with @<major>.<minor>.<patch> after it for one release, such as dev-tool@1.2.0. |
APPLICATION_NOT_FOUND | The catalog holds no release of an application of that name. | Check the name against the applications the catalog publishes. |
VERSION_NOT_RELEASED | The catalog holds releases of the application, but none of the version asked for built for this machine's platform; the message lists the versions it holds. | Ask for one of the versions the message lists, or for none to take the newest. |
PLATFORM_NOT_BUILT | The catalog holds no release of the application built for this machine's platform -- none at all, or none of the version asked for. | Install on a platform the application is released for; the message names the platforms it is built for where there are any. |
RELEASE_FILE_MISSING | The catalog lists the release but holds no file for it. | Report it against the catalog; nothing on this machine repairs it. |
RELEASE_DIGEST_UNRECORDED | The catalog records no digest for the release, so what it holds cannot be checked and is not used. | Report it against the catalog; nothing on this machine repairs it. |
RELEASE_DIGEST_MISMATCH | The file the catalog holds for the release is not the one that was released -- its digest differs from the one recorded -- so it is not used. | Run the command again, in case the download was damaged; if it fails the same way, report it against the catalog. |
RELEASE_NOT_UNPACKED | The release was obtained and checked, but could not be unpacked into place; the message says why. | Repair what the message names -- most often space or permission on the install directory -- and run the command again. |
RELEASE_HOLDS_NO_EXECUTABLE | The release unpacked holds no executable named for the application, so there is nothing to run. | Report it against the release; install another version meanwhile. |
APPLICATION_IN_USE | The installed version could not be replaced because a running copy of the application holds its files. | Close every running copy of the application and run the command again. |
TOKEN_MALFORMED | The distribution token given, kept for this user or stated in SOLIDPLANS_TOKEN is not shaped as one -- sps_pkg_ and 43 letters, digits, - or _ -- so it is not sent; the message says where it was read from. | Copy the token again from where it was issued, and set it with toolchain token set or in SOLIDPLANS_TOKEN. |
TOKEN_UNREADABLE | A distribution token is kept for this user, and its file could not be read; the message names the file and why. | Repair what the message names -- most often permission on the file -- or set the token again with toolchain token set. |
TOKEN_MISSING | The product's catalog answers only to a distribution token, and none was sent -- none is kept for this user and none is stated in SOLIDPLANS_TOKEN. | Set the token issued to you with toolchain token set, or state it in SOLIDPLANS_TOKEN. |
TOKEN_UNKNOWN | The distribution token sent is not one the product's catalog knows; the message says where it was read from. | Check it is the token issued to you, copied whole, and set it again; if it is, ask for a new one. |
TOKEN_REVOKED | The distribution token sent has been revoked, so the product's catalog no longer answers to it. | Ask for a new token, and set it with toolchain token set or state it in SOLIDPLANS_TOKEN. |
TOKEN_EXPIRED | The distribution token sent has expired, so the product's catalog no longer answers to it. Every command that fetches warns of this in the fortnight before it happens. | Ask for a new token, and set it with toolchain token set or state it in SOLIDPLANS_TOKEN. |
TOKEN_NOT_ENTITLED | The distribution token sent is good, and does not cover the application or library that was asked for. | Ask whoever issued the token for one that covers it. |
Also every code of pkgmgr:pkgmgr-store
| Code | Meaning | Remedy |
|---|---|---|
CATALOG_UPSTREAM_STORE_UNKNOWN | A catalog's configuration defers to a store by a label its own stores does not declare. | Declare the store under stores in that catalog's .pkgmgr/config.yml, or defer to one of the labels the message lists. |
STORE_LOCATION_NOT_PORTABLE | A store's location is a relative path that climbs out of the catalog naming it, which says something about one machine's layout rather than about the catalog. | Name the store by an absolute path or uri, or by a path beginning with ${CATALOG_ROOT}. |
STORE_LOCATION_VARIABLE_UNDECLARED | A store's location names an environment variable a store location may not name. | Use one of the variables the message lists -- ${CATALOG_ROOT} or ${CATALOG_REPO_ADAPTER} -- or write the location out. |
STORE_LOCATION_VARIABLE_UNSET | A store's location names a declared environment variable that nothing reads in place of when it is unset, and it is unset -- CATALOG_REPO_ADAPTER, the clone of an organization's repo adapter catalog, is one. | Set the variable the message names to the directory it stands for -- for CATALOG_REPO_ADAPTER, the clone of the organization's adapter catalog -- as a user or machine variable, or in the job's environment on a CI agent. |
STORE_LOCATION_UNREACHABLE | A store's location is not a directory that can be read now -- missing, unmounted, or served by an address that did not answer. | Make the location reachable, or point the store at one that is; the message says what kind of location the store's type takes. |
STORE_NOT_FOUND | The store named is not one the catalog's configuration declares. | Name one of the stores the message lists, or declare the store in the catalog's .pkgmgr/config.yml. |
STORE_AMBIGUOUS | More than one store is configured and the run did not say which one to use. | Pass --store naming one of the stores the message lists. |
STORE_FETCH_FAILED | A store that is fetched before it is read could not be fetched, so it is not read -- an earlier copy could answer with a release that has since been superseded. | Repair what the message quotes -- most often the network, or a credential the store's address needs -- and run the command again. |
STORE_ACCESS_REFUSED | A store served at an address refused the fetch -- 401 or 403 -- for want of a credential it takes or one that reaches the file; the message says whether a credential was given, and quotes what the server named. | Give the store a credential it takes, through whatever reads the store; the message names what the server said was wrong with the one given. |
STORE_DIRECTORY_OUTSIDE | A store fetched from a repository names a directory that is not inside that repository. | Write the store's directory relative to the root of the repository it is fetched from. |
STORE_ENTRY_OUTSIDE | A store's index records a path that is not inside the store, so nothing is fetched to it. | Report it against the store; its index is not one this tool will follow. |
STORE_ARTIFACT_DIGEST_MISMATCH | A file a store served is not the one its index records -- the sha256 differs -- so it was not kept. | Run the command again, in case the transfer was damaged; if it fails the same way, report it against the store. |
STORE_CREDENTIAL_INSECURE | A store was given a credential, and its address is not https:, so sending the credential would put it on the network in the clear. | Name the store by an https: address. |
STORE_UPDATE_NOT_A_CHECKOUT | A store asks to be brought up to date before it is read or written, and its directory is not a git checkout, so there is nothing to pull. | Clone the catalogs' repository at that directory, or drop the setting asking for the update from the store. |
STORE_UPDATE_NO_UPSTREAM | A store asks to be brought up to date, and the checkout holding it has no upstream branch to pull. | Check out a branch in that checkout that tracks the catalogs' remote. |
STORE_UPDATE_NOT_FAST_FORWARD | A store could not be brought up to date because pulling into its checkout does not fast-forward -- the checkout holds a change nobody else has. | Resolve the checkout by hand -- push or drop the local change -- and run the command again. |
STORE_READ_ONLY | The command would write to a store that is fetched and only ever read. | Write to a checkout of that store instead -- a local store whose location names the clone. |
COORDINATE_INVALID | A package was named by something that is not a coordinate. | Write it as namespace:name@major.minor.patch, the version in full, or as namespace:name or namespace:name@latest for the highest version held. |
COORDINATE_MUST_PIN | A coordinate names no version, and what was asked needs one. | Add the version in full, namespace:name@<major.minor.patch>. |
ARTIFACT_REGISTRATION_FAILED | An artifact could not be registered in the store; the message names the file and what failed. | Repair what the message names -- most often the artifact itself, or the store's permissions -- and register it again, with pkgmgr pkg register for a file you hold. |
VERSION_CLOBBER | The store already holds that version of the package with different content, and a version is written once. | Release the next version instead of rewriting this one. |
COPY_ENTRY_NOT_HELD | The store being copied from holds no entry for that version of the package. | Name a version the source store holds. |
COPY_ARTIFACT_MISSING | The source store indexes the version, but holds no files for it, so there is nothing to copy. | Clear the entry with pkgmgr pkg clear and register the version into the source store again with pkgmgr pkg register, or report it against that store. |
COPY_FAILED | Copying the entry's files into the target store failed; the message carries the operating system's error. | Repair what the message names -- most often space or permission on the target -- and copy again. |
AUDIENCE_UNKNOWN | The audience given is not one a release has. | Give one of the audiences the message lists. |
AUDIENCE_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record an audience on. | Register the version first, or name one the store holds. |
CLIENT_NOTES_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record client notes on. | Register the version first, or name one the store holds. |
DEPENDENCIES_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record its dependencies on. | Register the version first, or name one the store holds. |
LANGUAGE_VERSIONS_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record language versions on. | Register the version first, or name one the store holds. |
LANGUAGE_VERSIONS_INVALID | The language versions given are not a version range, so nothing was recorded. | Write a version (3.13), a list of them ([3.13, 3.14]), or bounds joined by a comma (>=3.13,<3.15). |
NOTES_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record release notes on. | Register the version first, or name one the store holds. |
README_ENTRY_NOT_HELD | The store holds no entry for that version of the package to record a README on. | Register the version first, or name one the store holds. |
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.update
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
previousVersion | version | Yes | The version that was running when the command started | |
currentVersion | version | Yes | The version in use once the command has run: the release it installed, or the one that was running where nothing changed | |
requestedVersion | version | No | The release --to named, absent where none was named and the newest was meant | |
targetVersion | version | No | The release this run was to move to: the one --to named, or the newest the store holds for this platform. Absent where the application was not installed or the store held no such release | |
updated | boolean | No | false | Whether this run installed a release: a newer one, or with --force an older one |
platform | string | No | The platform of this machine, which is the one a release is installed for; absent where the application was not installed, so no catalog was asked | |
coordinate | pinnedCoordinate | No | The catalog entry the release installed was read from, absent where none was installed | |
launcher | path | No | The launcher this run wrote, which is what the application is run as | |
leftBehind | list[path] | No | [] | The version that was running, which holds its own files open and is removed by the next update |
notesSince | string | No | The version of the last release clients received, which the notes below run from; absent for the first, and where the release carries no notes | |
changes | list[string] | No | [] | What the release installed changed that whoever runs it can observe, one line each |
considerations | list[string] | No | [] | What whoever runs it has to act on, one line each, with what to do about it where the release says |