<commit_before># Using the Client

`updatectl` lets you control and test the CoreOS update service. Subcommands
let you manage apoplications, users, groups, packages and write a very simple client that gets
its state via environment variables.

## Update Clients

There are two tools to test out the update service: `instance fake` and `watch`.
`instance fake` simulates a number of clients from a single
command. `watch` is
used to quickly implement a simple update client with a minimal amount of code.

### Fake Instances

This example will start 132 fake instances pinging the update service every 1 to
50 seconds against the CoreOS application's UUID and put them in the beta group
starting at version 1.0.0.

```
./bin/updatectl instance fake --clients-per-app 132 --min-sleep 1 \
	--max-sleep 50 --app-id e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--group-id beta --version 1.0.0
```

### Update Watcher

`instance fake` is useful for generating traffic but if you want a fast way to
create your own client you can use `watch`. This will exec a program of your
choosing every time a new update is available.

First, create a simple application that dumps the environment variables that
the watcher will pass in. Call the script `updater.sh`.

```
#!/bin/sh
env | grep UPDATE_SERVICE
```

Next we will generate a random client id with and start watching for changes to the given app:

```
./bin/updatectl watch --app-id e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--group-id beta ./updater.sh
```

If you change the version of the beta group's channel then your script will be
re-executed and you will see the UPDATE_SERVICE environment variables change.

## Administative Flags

There are a few flags that you must provide to the administrative commands below.

- `--user` is your username, usually this is an email address or `admin`
- `--key` is your API key
- `--server` is the URL to your update service instance

The commands below will all have a prefix like this:

```
./bin/updatectl --user admin --key d3b07384d113edec49eaa6238ad5ff00 --server https://example.update.core-os.net
```

If you do not wish to specifiy `--user` and `--key` every time, they
can also be exported as environment variables like this:

```
export UPDATECTL_USER=admin
export UPDATECTK_KEY=d3b07384d113edec49eaa6238ad5ff00
```

## Application Management

Applications have three pieces of data: a universal unique identifier
(UUID), a label (name) and a description. The UUID is used by all of
the updaters to tell the service what application they belong to.

### Add an Application

Create an application called CoreOS using its UUID along with a nice description.

```
./bin/updatectl app create --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 --label="CoreOS" --description="Linux for Servers"
```

### List Applications

```
./bin/updatectl app list
```

## Package Management

Packages represent an individual version of an application and the URL
associated with it.

### Add an Application Version

This will create a new package with version 1.0.5 from the file `update.gz`.

```<commit_msg>doc(client.md): make changes, fix typo<commit_after># Using the Client

`updatectl` lets you control and test the CoreOS update service. Subcommands
let you manage applications, users, groups, packages and write a very simple client that gets
its state via environment variables.

## Update Clients

There are two tools to test out the update service: `instance fake` and `watch`.
`instance fake` simulates a number of clients from a single
command. `watch` is
used to quickly implement a simple update client with a minimal amount of code.

### Fake Instances

This example will start 132 fake instances pinging the update service every 1 to
50 seconds against the CoreOS application's UUID and put them in the beta group
starting at version 1.0.0.

```
./bin/updatectl instance fake --clients-per-app 132 --min-sleep 1 \
	--max-sleep 50 --app-id e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--group-id beta --version 1.0.0
```

### Update Watcher

Real clients should implement the Omaha protocol but if you want a fast way to
create your own client you can use `watch`. This will exec a program of your
choosing every time a new update is available.

First, create a simple application that dumps the environment variables that
the watcher will pass in. Call the script `updater.sh`.

```
#!/bin/sh
env | grep UPDATE_SERVICE
```

Next we will generate a random client id with and start watching for changes to the given app:

```
./bin/updatectl watch --app-id e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--group-id beta ./updater.sh
```

If you change the version of the beta group's channel then your script will be
re-executed and you will see the UPDATE_SERVICE environment variables change.

## Administative Flags

There are a few flags that you must provide to the administrative commands below.

- `--user` is your username, usually this is an email address or `admin`
- `--key` is your API key
- `--server` is the URL to your update service instance

The commands below will all have a prefix like this:

```
./bin/updatectl --user admin --key d3b07384d113edec49eaa6238ad5ff00 --server https://example.update.core-os.net
```

If you do not wish to specifiy `--user` and `--key` every time, they
can also be exported as environment variables like this:

```
export UPDATECTL_USER=admin
export UPDATECTK_KEY=d3b07384d113edec49eaa6238ad5ff00
```

## Application Management

Applications have three pieces of data: a universal unique identifier
(UUID), a label and a description. During a request to the update
service, the UUID is submitted in order to retrieve the details of the
currently available version.

### Add an Application

Create an application called CoreOS using its UUID along with a nice description.

```
./bin/updatectl app create --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 --label="CoreOS" --description="Linux for Servers"
```

### List Applications

```
./bin/updatectl app list
```

## Package Management

Packages represent an individual version of an application and the URL
associated with it.

### Add an Application Version

This will create a new package with version 1.0.5 from the file `update.gz`.

```
{'fraction_non_alphanumeric': 0.08074634067878397, 'fraction_numerical': 0.03570854109699212, 'mean_word_length': 4.084219133278823, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '624755', 'n_tokens_mistral': 1953, 'n_tokens_neox': 1783, 'n_words': 857}