From 6543daa5fe45467c598e50acfa0d408fda2b0c97 Mon Sep 17 00:00:00 2001
From: Giselle van Dongen <giselle.vd@gmail.com>
Date: Thu, 11 Jan 2024 09:19:37 +0100
Subject: [PATCH] Add Restate CLI docs (#249)

---
 docs/restate/cli.mdx            | 138 ++++++++++++++++++++++++++++++++
 docs/restate/logging.md         |   2 +-
 docs/restate/managed_service.md |   2 +-
 docs/restate/tracing.mdx        |   2 +-
 4 files changed, 141 insertions(+), 3 deletions(-)
 create mode 100644 docs/restate/cli.mdx

diff --git a/docs/restate/cli.mdx b/docs/restate/cli.mdx
new file mode 100644
index 00000000..df9ea263
--- /dev/null
+++ b/docs/restate/cli.mdx
@@ -0,0 +1,138 @@
+---
+sidebar_position: 4
+description: "Use the CLI to interact with Restate."
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# CLI 
+
+You can use the CLI to interact with Restate, and manage your services, deployments and invocations.
+
+## Installation
+
+Install the Restate CLI via:
+
+<Tabs groupId="operating-systems">
+<TabItem value="lin" label="npm">
+
+```shell
+npm install @restatedev/restate
+```
+
+</TabItem>
+<TabItem value="mac" label="Homebrew">
+
+```shell
+brew install restatedev/tap/restate
+```
+
+</TabItem>
+</Tabs>
+
+
+## Configuration
+
+There are two ways to configure the CLI: via environment variables or via a configuration file.
+
+### Using environment variables
+
+You can specify the following environment variables:
+
+- `RESTATE_HOST`: The hostname/IP address of the server. Default is `localhost`.
+- `RESTATE_HOST_SCHEME`: Default is `http`.
+- `RESTATE_META_URL`: To specify the full URL of meta service (scheme+host+port).
+- `RESTATE_DATAFUSION_HTTP_URL`: To specify the full URL of datafusion HTTP endpoint.
+- `RESTATE_AUTH_TOKEN`: Set if authentication is required.
+
+For example, to specify the hostname `myhost` and the host scheme `https`, pass environment variables as follows:
+
+```shell
+RESTATE_HOST=myhost RESTATE_HOST_SCHEME=https restate <command>
+```
+
+### Using a configuration file
+
+You can also specify the configuration in a `.env` file. The CLI will look for a `.env` file in its current directory.
+
+For example, to connect to a Restate meta running at `http://myhost:7777`, save the following in a `.env` file:
+
+```
+RESTATE_META_URL=http://myhost:7777
+```
+
+## Usage
+
+Here are a few useful commands:
+
+**Check if the CLI is configured correctly**
+
+```shell
+restate whoami
+```
+
+
+**Printing help**
+
+```shell 
+restate --help
+```
+
+**Downloading an example or template**
+
+```shell
+restate example
+```
+
+Follow the prompts to select which template you want to download.
+
+**Listing your services**
+
+```shell
+restate svc list
+```
+
+**Show the status of the service(s)**
+
+```shell
+restate svc status
+```
+
+Shows a summary of the services and their methods.
+It shows counters for the invocations in the various states (pending, running, suspended, etc.)
+It also lists a sample of active service keys.
+
+To print the status of a specific service:
+
+```shell
+restate svc status <SERVICE_NAME>
+```
+
+**Listing ongoing invocations**
+
+```shell
+restate inv list
+```
+
+**Describing the status of an invocation**
+
+```shell
+restate inv describe <INVOCATION_ID>
+```
+
+Use this command to understand the progress of the invocation: the status, any errors and retries that occurred, the current journal, etc.
+
+**Cancel an ongoing invocation**
+
+```shell
+restate inv cancel <INVOCATION_ID>
+```
+
+Use this command to cancel an invocation and its children. 
+Use the `--kill` flag to ungracefully kill the invocation and its children.
+
+:::tip
+The CLI can be a useful tool for debugging and troubleshooting.
+Have a look at the [introspection page](/services/introspection) for a list of useful commands .
+:::
\ No newline at end of file
diff --git a/docs/restate/logging.md b/docs/restate/logging.md
index 337895b6..6e9ffe38 100644
--- a/docs/restate/logging.md
+++ b/docs/restate/logging.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 description: "Find out how to configure logging for Restate."
 ---
 
diff --git a/docs/restate/managed_service.md b/docs/restate/managed_service.md
index d2c97a34..55797522 100644
--- a/docs/restate/managed_service.md
+++ b/docs/restate/managed_service.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 description: "Try out Restate without any servers."
 ---
 
diff --git a/docs/restate/tracing.mdx b/docs/restate/tracing.mdx
index fb2ee0a6..4fa1264f 100644
--- a/docs/restate/tracing.mdx
+++ b/docs/restate/tracing.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 6
 description: "Find out how to export traces of your invocations."
 ---