docs: the CLI is a Go binary now and covers what the API does

integrate-with-steadybit/README.md

@@ -6,7 +6,7 @@ Steadybit is highly flexible, and you can seamlessly integrate it into your use
 
 ### Command-Line Interface (CLI)
 
-The CLI is ideal for integrating experiment runs, or advice checks, into your Continuous Integration/Continuous Delivery (CI/CD) pipeline. Under the hood, it uses the platform's [API](./#api). Because the CLI is an npm package, it is agnostic to your actual CI/CD tool in action. [Learn more about the CLI](cli.md).
+The CLI is ideal for running experiments and checking advice in your Continuous Integration/Continuous Delivery (CI/CD) pipeline, and for keeping experiments, templates, schedules, services, and the platform's configuration as files in Git. Under the hood, it uses the platform's [API](./#api). It is a single binary for Linux, macOS, and Windows, also available as a container image and a GitHub Action, so it works with any CI/CD tool. [Learn more about the CLI](cli.md).
 
 ### API
 
@@ -51,11 +51,15 @@ The remaining Extension Kits ([AdviceKit](extensions/extension-kits.md#advicekit
 
 ### CLI vs. API
 
-|     | [Validate advice status](../use-steadybit/explorer/advice.md) | [CRUD of experiments](../use-steadybit/experiments/design.md) | [Run experiments](../use-steadybit/experiments/run.md) | [Use experiment templates](../use-steadybit/experiments/design.md#from-template) | [Schedule Experiments](../use-steadybit/experiments/schedule/) | [Emergency stop](../use-steadybit/experiments/emergencyStop.md) | [Read targets](../use-steadybit/explorer/targets.md) | [Configure Steadybit](#user-content-fn-2)[^2] |
-| --- | ------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------- |
-| CLI | ✅                                                             | ✅                                                             | ✅                                                      | ❌                                                                                | ❌                                                              | ❌                                                               | ❌                                                    | ❌                                             |
-| API | ✅                                                             | ✅                                                             | ✅                                                      | ✅                                                                                | ✅                                                              | ✅                                                               | ✅                                                    | ✅                                             |
+The CLI covers the same use cases as the API. It runs experiments, checks advice, and triggers the emergency stop. It manages experiments, templates, schedules, services, teams, environments, access tokens, integrations, and the rest of the platform's configuration. It reads targets, reports, and the audit log. Because it calls the API under the hood, the difference is how you work with it:
 
-[^1]: Only when the action is part of the experiment design and is currently running.
+|                       | CLI                                                                                                                               | API                                                                                                       |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Best for              | CI/CD pipelines and GitOps, one command per step                                                                                  | Your own tools and integrations, in any language                                                          |
+| Setup                 | One binary, a container image, or a GitHub Action                                                                                 | Any HTTP client, or a client generated from the [OpenAPI specification](api/api.md#openapi-specification) |
+| Configuration as code | Files in Git: `apply`, `diff` (exits with 2 on drift), and `export` of a whole team                                               | One JSON or YAML request per resource                                                                     |
+| Running experiments   | Waits for the run, fails the pipeline when the run fails, cancels the run when the pipeline is canceled, and writes JUnit reports | Start the run, then poll its state                                                                        |
+
+A few things are only available through the API: the license report, target statistics, saved landscape views, experiment badges, and searching runs across all experiments.
 
-[^2]: Administrative functionality like managing [teams and users](../install-and-configure/manage-teams-and-users/), [environments](../install-and-configure/manage-environments/), [experiment templates](../install-and-configure/manage-experiment-templates/), [hub connections](hubs/), and [properties](../install-and-configure/manage-properties/).
+[^1]: Only when the action is part of the experiment design and is currently running.

integrate-with-steadybit/cli.md

@@ -4,20 +4,58 @@ title: CLI
 
 # CLI
 
-The [Steadybit CLI](https://github.com/steadybit/cli) lets you connect your repository to Steadybit and keep a single source of truth for all your experiments. Because you can create, update and retrieve your experiment definitions from it, they stay versioned in one place. Of course, you can also run your experiments from the command line interface.
-
-This allows you to implement GitOps practices easily.
+The [Steadybit CLI](https://github.com/steadybit/cli) runs experiments from your CI/CD pipeline and keeps your chaos engineering setup in Git: experiments, templates, schedules, services, service profiles, environments, teams, properties, and integrations. It is a single binary for Linux, macOS, and Windows that calls the [API](api/api.md) under the hood.
 
 ## Installation
 
-Installation is nothing more than:
+With Homebrew on macOS or Linux, which also installs the shell completions:
 
 ```bash
-npm install -g steadybit
+brew install steadybit/tap/steadybit
 ```
 
-Afterwards, you have to create a profile and authenticate via an [access token](api/api.md#access-tokens). Check out our public GitHub repository [steadybit CLI](https://github.com/steadybit/cli#authorization) to learn more.
+Alternatively:
+
+* **Download** the archive for your platform from the [releases](https://github.com/steadybit/cli/releases) and put `steadybit` on your `PATH`:
+
+  ```bash
+  curl -sL https://github.com/steadybit/cli/releases/latest/download/steadybit_linux_amd64.tar.gz | tar -xz steadybit
+  sudo mv steadybit /usr/local/bin/
+  ```
+* **Container image**: `steadybit/cli`, for example `docker run --rm -e STEADYBIT_TOKEN steadybit/cli experiment run -k ADM-1 --yes`
+* **GitHub Actions**: `uses: steadybit/cli@v6` installs the CLI on the runner.
+* **Go**: `go install github.com/steadybit/cli/v6/cmd/steadybit@latest`
+
+{% hint style="info" %}
+Up to version 5, the CLI was an npm package. That package is no longer updated: uninstall it with `npm uninstall -g steadybit` and install the CLI as above. Commands, flags, and profiles in `~/.steadybit` keep working.
+
+The `steadybit/run-experiment` GitHub Action is deprecated in favor of the CLI, which does everything it does. Each of its inputs has an `experiment run` flag: see [moving from steadybit/run-experiment](https://github.com/steadybit/cli#moving-from-steadybitrun-experiment).
+{% endhint %}
+
+## Authentication
+
+The CLI needs an [access token](api/api.md#access-tokens). Store it in a profile:
+
+```bash
+steadybit config profile add
+```
+
+In a pipeline, set the environment variables `STEADYBIT_TOKEN` and, for an on-prem installation, `STEADYBIT_URL` instead.
 
 ## Usage
 
-The CLI is largely self-explanatory. For detailed documentation, have a look at our public GitHub repository, [steadybit/cli](https://github.com/steadybit/cli).
+Run an experiment in a pipeline. The command waits for the run and fails when the run fails, cancels the run when the pipeline is canceled, and writes a JUnit report:
+
+```bash
+steadybit experiment run -f experiment.yml --yes --timeout 30m --report steadybit.xml
+```
+
+Keep a team's experiments, schedules, services, and custom service profiles in Git:
+
+```bash
+steadybit export --team ADM -d ./chaos    # write them as files
+steadybit diff -d ./chaos                 # what differs from the platform; exits with 2 if anything does
+steadybit apply -d ./chaos                # create or update them on the platform
+```
+
+Every command documents its options and examples in `--help`, for example `steadybit experiment run --help`. The [README](https://github.com/steadybit/cli#readme) covers everything else, including GitLab CI and shell completion.