# Quick Start<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

== Description

Updatecli applies update strategies described in a manifest.
This guide builds the smallest useful one: a data file pinning a Docker image tag, and a
manifest that keeps that tag in sync with the latest Jenkins weekly release.

Everything happens in a single directory, and nothing is pushed anywhere.

== Requirements

The `updatecli` binary must be installed.
If it is not, follow the link:/docs/prologue/installation/[Installation guide] first, then
check it is reachable:

[source,shell]
----
updatecli version
----

== Scenario

Create an empty directory and work from there.
Two files are needed: the data file to update, and the manifest describing how to update it.

.The three stages of a pipeline
image::/images/diagrams/pipeline.png["Updatecli Pipeline"]

=== The data file

This is the file Updatecli will keep up to date.
It declares the "latest" Jenkins Docker image tag running in our infrastructure.

.data.yaml
[source,yaml]
----
{{<include "assets/code_example/docs/prologue/quickstart/data.yaml">}}
----

=== The manifest

The manifest declares the update strategy.
It introduces the three stages Updatecli runs, in the order it runs them:

**Source**::
Where a piece of information comes from.
Here, the latest Jenkins weekly version.

**Condition**::
What must be true before anything is written.
Here, the Docker image `jenkins/jenkins:<latest weekly version>` must exist on DockerHub.

**Target**::
What to update with the source value.
Here, the key `$.container.tag` of `data.yaml`.

.updatecli.yaml
[source,yaml]
----
{{<include "assets/code_example/docs/prologue/quickstart/updatecli.yaml">}}
----

Each stage behaves differently depending on the plugin it uses, which is what the `kind` key
selects. The same `yaml` kind used here as a target can also be used as a source or a condition.

TIP: Neither the condition nor the target names a source explicitly.
When a manifest declares exactly one source, Updatecli wires it up on its own.
With more than one, use `sourceid` to say which value to use.

== Run it

Updatecli looks for a file named `updatecli.yaml`, or a directory named `updatecli.d`, in the
current directory. Since the manifest above is named `updatecli.yaml`, no flag is needed.

First, see what would change:

[source,shell]
----
updatecli diff
----

[source,text]
----
{{<include "assets/code_example/docs/prologue/quickstart/output.txt">}}
----

Nothing has been written yet: `diff` is read-only.

Now apply the change:

[source,shell]
----
updatecli apply
----

`data.yaml` is updated in place, and the target line reads
`key "$.container.tag" updated from "2.475" to "2.575", in file "data.yaml"`.

Run the same command again:

[source,shell]
----
updatecli apply
----

[source,text]
----
✔ - no change detected:
	* key "$.container.tag" already set to "2.575", from file "data.yaml"
----

The second run changes nothing. Updatecli is idempotent: it describes the state a file should
be in, not a sequence of edits, so running it repeatedly is safe and is exactly what makes it
usable from a scheduled CI job.

NOTE: The versions in the output above are whatever the latest Jenkins weekly was when this
page was written. Yours will differ.

== Conclusion

This pipeline is deliberately small. From here it can grow in every direction: committing the
result to a Git repository, opening a pull request instead of writing in place, reshaping the
source value with link:/docs/core/transformer/[transformers], or pinning to a release range
with a link:/docs/core/versionfilter/[version filter].

The real power of Updatecli is combining plugins so the update workflow matches your project,
rather than the other way round.

== Go Further

* link:/docs/core/[Core] - the concepts behind a manifest, stage by stage.
* link:/docs/core/scm/[SCM] and link:/docs/core/action/[Action] - commit the result and open a pull request.
* link:/docs/core/autodiscovery/[Autodiscovery] - let Updatecli write the manifests for you.
* link:/docs/plugins/[Plugins] - every source, condition, target, scm, action, and crawler available.
* link:/docs/automate/[Automate] - run this continuously from your CI environment.
* link:/docs/commands/[Commands] - the full command line reference.
* link:/docs/help/[Help] - FAQ, deprecations, and where to ask questions.