Update a Tool and manage versions

Tool maintenance starts by checking existing versions and the available modes. The operator then explicitly selects an in-place update or a new version. fkit defaults to check mode; it does not infer a write mode or switch modes after a failure.

Check and choose

fkit update NAME lists positive integer versions, the next version, and the available modes. Use fkit update NAME:VERSION to select a baseline. Versions must be positive integers. If a name has multiple versions, inspect the choices and select a baseline instead of assuming one is safe to edit in place.

In-place update

In-place mode requires an exact version and a config JSON file, a Markdown summary, or both:

fkit update NAME:VERSION --mode in-place --config tool.json --dry-run
fkit update NAME:VERSION --mode in-place --config tool.json --summary summary.md

fkit does not scan Flow references locally, so it cannot tell before submitting whether a version is referenced. BioLine server enforcement is the only authority: if a Flow still references the version, the server rejects the update, and fkit surfaces the underlying error unchanged without retrying, changing modes, or creating a fallback version.

Config and summary use separate update requests. When both are supplied, config is sent first and summary second. The summary request reuses the command that was just prepared, so it cannot revert the configuration written moments earlier. If the second request fails, fkit reports that config was applied and summary was not. This sequence is not atomic.

Create a new version

New-version mode no longer needs a local image: fkit reuses the image already stored on the server for the baseline. The baseline can be the latest positive version for a name or an explicitly selected version:

fkit update NAME --mode new-version --dry-run
fkit update NAME:VERSION --mode new-version --config tool.json --summary summary.md

--dry-run checks the config and summary files, merges the patch over the baseline configuration, validates the command, and confirms that the baseline exposes a reusable path, without creating or updating remote objects. A real creation request is attempted once. fkit then rereads the Tool and requires the same Tool ID, every old version to remain, and exactly the expected positive integer version to be added. If the result cannot be verified, it does not guess an ID or continue writing.

The create request itself carries the command, summary, endpoints, and machine configuration, so one write is normally enough: the new version is born with the command and summary submitted in that call, and no second update call is needed to copy configuration over. fkit then reads the version back to check it. If BioLine did not keep the configuration carried by the create request (for example, the new version still shows the baseline summary), fkit sends exactly one update against the version it just created and verifies again. It never writes more than that and never loops, so every version keeps its own summary. In --json output, configSource says which request supplied the configuration and remoteWriteCalls reports the number of writes actually issued (normally 1).

Output and safety boundary

--json emits check results or operation status, including before/after versions, baseline, creation verification, configuration verification (configVerified, configSource), the number of remote writes (remoteWriteCalls), and partial success. Authentication and remote reads use the selected fkit project configuration. Command documentation mode --docs returns its page before authentication or business actions.