More CLI 3.0 config docs and references

ku1ik · ku1ik · commit 67fa77e0b543 · 2025-06-03T21:25:01.000+02:00
diff --git a/docs/manual/cli/configuration/index.md b/docs/manual/cli/configuration/index.md
@@ -0,0 +1,41 @@
+# Configuration
+
+You can configure asciinema CLI with a config file.
+
+The most common use-case is setting the URL of a [self-hosted asciinema
+server](../../server/self-hosting/index.md):
+
+=== "CLI 3.x"
+
+    ```toml title="~/.config/asciinema/config.toml"
+    [server]
+    url = "https://asciinema.example.com"
+    ```
+
+=== "CLI 2.x"
+
+    ```ini title="~/.config/asciinema/config"
+    [api]
+    url = https://asciinema.example.com
+    ```
+
+Alternatively you can set it with environment variable in your shell config
+file:
+
+=== "CLI 3.x"
+
+    ```sh title="~/.bashrc"
+    export ASCIINEMA_SERVER_URL=https://asciinema.example.com
+    ```
+
+=== "CLI 2.x"
+
+    ```sh title="~/.bashrc"
+    export ASCIINEMA_API_URL=https://asciinema.example.com
+    ```
+
+There's more things you can configure. For the full list of options check out
+the documentation for asciinema CLI version you use:
+
+- [CLI 2.x configuration](v2.md)
+- [CLI 3.x configuration](v3.md)
diff --git a/docs/manual/cli/desktop-notifications.md b/docs/manual/cli/desktop-notifications.md
@@ -21,12 +21,21 @@ the state of the terminal. This works out of the box on Linux (via
     of a program currently running in the foreground, e.g. a shell, vim etc.
 
 You can disable desktop notifications with the `notifications.enabled` option in
-the [config file](configuration.md):
+the [config file](configuration/index.md):
 
-```ini title="~/.config/asciinema/config"
-[notifications]
-enabled = no
-```
+=== "CLI 3.x"
+
+    ```toml title="~/.config/asciinema/config.toml"
+    [notifications]
+    enabled = false
+    ```
+
+=== "CLI 2.x"
+
+    ```ini title="~/.config/asciinema/config"
+    [notifications]
+    enabled = no
+    ```
 
 ## Custom notification command
 
@@ -40,10 +49,19 @@ The command is executed with the following environment variables:
 Below is an example of [tmux](https://github.com/tmux/tmux/wiki) status bar
 integration:
 
-```ini title="~/.config/asciinema/config"
-[notifications]
-command = tmux display-message "$TEXT"
-```
+=== "CLI 3.x"
+
+    ```toml title="~/.config/asciinema/config.toml"
+    [notifications]
+    command = 'tmux display-message "$TEXT"'
+    ```
+
+=== "CLI 2.x"
+
+    ```ini title="~/.config/asciinema/config"
+    [notifications]
+    command = tmux display-message "$TEXT"
+    ```
 
 The command is executed in a shell (`/bin/sh`), therefore it's possible to use
 shell constructs like pipes.
diff --git a/docs/manual/cli/markers.md b/docs/manual/cli/markers.md
@@ -11,7 +11,7 @@ Markers can be added to a recording in two ways.
 
 During a recording session, you can add markers in real-time by pressing a
 configured [keyboard shortcut](shortcuts.md). Set `rec.add_marker_key` [config
-file option](configuration.md) first as there's no default binding at the
+file option](configuration/index.md) first as there's no default binding at the
 moment. When a marker is added a [desktop
 notification](desktop-notifications.md) is displayed.
 
diff --git a/docs/manual/cli/shortcuts.md b/docs/manual/cli/shortcuts.md
@@ -1,40 +1,54 @@
+---
+hide:
+  - toc
+---
+
 # Keyboard shortcuts
 
 There are several key bindings used by the CLI during recording and playback.
-Most of them can be customized in the [config file](configuration.md).
+Most of them can be customized in the [config file](configuration/index.md).
 
 ## Recording shortcuts
 
 The following keyboard shortcuts are available when recording with [`asciinema
 rec`](usage.md#asciinema-rec-filename):
 
-shortcut | action | config file option | notes
----------|--------|---------------|------
-<kbd>ctrl+\</kbd> | toggle the capture of a terminal | `rec.pause_key` | similar to "mute" on an audio call
-<kbd>ctrl+d</kbd> | end the recording session | - | this is handled by a shell
-- | add a [marker](markers.md) | `rec.add_marker_key` | no default shortcut for this
+shortcut | action | 3.x config file option | 2.x config file option | notes
+---------|--------|---------------|------|---
+<kbd>ctrl+\</kbd> | toggle the capture of a terminal | `recording.pause_key` | `rec.pause_key` | similar to "mute" on an audio call
+<kbd>ctrl+d</kbd> | end the recording session | - | - |  this is handled by a shell
+- | add a [marker](markers.md) | `recording.add_marker_key` | `rec.add_marker_key` | no default shortcut for this
 
 ## Playback shortcuts
 
 The following keyboard shortcuts are available when replaying with [`asciinema
 play`](usage.md#asciinema-play-filename):
 
-shortcut | action | config file option | notes
----------|--------|---------------|------
-<kbd>space</kbd> | toggle the playback | `play.pause_key` | pauses / resumes
-<kbd>]</kbd> | jump to next [marker](markers.md) | `play.next_marker_key` |
-<kbd>.</kbd> | step (when paused) | `play.step_key` | steps through a recording<br>a frame at a time
-<kbd>ctrl+c</kbd> | stop | - | ends the playback
+shortcut | action | 3.x config file option | 2.x config file option | notes
+---------|--------|---------------|------|---
+<kbd>space</kbd> | toggle the playback | `playback.pause_key` | `play.pause_key` | pauses / resumes
+<kbd>]</kbd> | jump to next [marker](markers.md) | `playback.next_marker_key` | `play.next_marker_key` |
+<kbd>.</kbd> | step (when paused) | `playback.step_key` | `play.step_key` | steps through a recording<br>a frame at a time
+<kbd>ctrl+c</kbd> | stop | - | - | ends the playback
 
 ## Prefix key
 
 You can define a "prefix key" for the recording shortcuts with `rec.prefix_key`
 option in the config file:
 
-```ini title="~/.config/asciinema/config"
-[rec]
-prefix_key = C-a
-```
+=== "CLI 3.x"
+
+    ```toml title="~/.config/asciinema/config.toml"
+    [recording]
+    prefix_key = "C-a"
+    ```
+
+=== "CLI 2.x"
+
+    ```ini title="~/.config/asciinema/config"
+    [rec]
+    prefix_key = C-a
+    ```
 
 This works similarly to a prefix key in [GNU
 screen](https://www.gnu.org/software/screen/) or
diff --git a/docs/manual/cli/usage.md b/docs/manual/cli/usage.md
@@ -18,7 +18,7 @@ You can temporarily pause the capture of your terminal by pressing
 that must not be captured (e.g. pasting secrets). It's an equivalent of the
 "mute" functionality in an audio call. Resume the capture by pressing
 <kbd>ctrl+\</kbd> again. This shortcut (and [other shortcuts](shortcuts.md)) can
-be customized in the [config file](configuration.md). Capture state changes are
+be customized in the [config file](configuration/index.md). Capture state changes are
 signaled via [desktop notifications](desktop-notifications.md).
 
 Recording session ends when you exit the shell, which can be done either by
@@ -175,7 +175,7 @@ This command uploads a terminal session recorded with `rec` to [asciinema
 server](../server/index.md) instance, where it can be viewed and shared with a
 wider audience. Default upload target is [asciinema.org](https://asciinema.org),
 but it can be easily changed to [point to another server
-instance](configuration.md#asciinema_api_url).
+instance](configuration/v3.md#asciinema_server_url).
 
 It's likely that you would want to manage this and other uploaded recordings at
 some point, e.g. set a title or change terminal color theme. See [asciinema
diff --git a/docs/manual/player/markers.md b/docs/manual/player/markers.md
@@ -71,7 +71,7 @@ definitions:
 [17.389425, "o", "..."]
 ```
 
-asciinema recorder can be [configured](../cli/configuration.md) to have a
+asciinema recorder can be [configured](../cli/configuration/index.md) to have a
 keyboard shortcut for adding markers during the recording session. If you have
 an existing recording you can edit the file with your favourite editor and
 insert marker lines as shown in the above example.
diff --git a/docs/manual/server/self-hosting/index.md b/docs/manual/server/self-hosting/index.md
@@ -32,12 +32,22 @@ secure asciinema server easily.
 
 Once your server is up and running, you'll be able to upload your recordings by
 pointing [asciinema CLI](../../cli/index.md) to the server using the
-`ASCIINEMA_API_URL` environment variable:
+`ASCIINEMA_SERVER_URL` environment variable:
+
+=== "CLI 3.x"
+
+    ```sh
+    export ASCIINEMA_SERVER_URL=https://asciinema.example.com
+    asciinema upload demo.cast
+    ```
+
+=== "CLI 2.x"
+
+    ```sh
+    export ASCIINEMA_API_URL=https://asciinema.example.com
+    asciinema upload demo.cast
+    ```
 
-```sh
-export ASCIINEMA_API_URL=https://asciinema.example.com
-asciinema upload demo.cast
-```
 
 If you need help with installation or maintenance feel free to ask on [asciinema
 forum](https://discourse.asciinema.org) or in [asciinema Matrix
diff --git a/docs/manual/server/self-hosting/quick-start.md b/docs/manual/server/self-hosting/quick-start.md
@@ -174,10 +174,19 @@ Congratulations! You have your own asciinema server instance 🎉
 Now, point asciinema CLI to your server by setting `ASCIINEMA_API_URL`, and
 upload a recording:
 
-```sh
-export ASCIINEMA_API_URL=https://asciinema.example.com
-asciinema upload demo.cast
-```
+=== "CLI 3.x"
+
+    ```sh
+    export ASCIINEMA_SERVER_URL=https://asciinema.example.com
+    asciinema upload demo.cast
+    ```
+
+=== "CLI 2.x"
+
+    ```sh
+    export ASCIINEMA_API_URL=https://asciinema.example.com
+    asciinema upload demo.cast
+    ```
 
-Check the [CLI configuration](../../cli/configuration.md) section for
+Check the [CLI configuration](../../cli/configuration/index.md) section for
 information on how to set the server URL permanently via the configuration file.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -61,6 +61,7 @@ nav:
       - manual/cli/installation.md
       - manual/cli/usage.md
       - Configuration:
+        - manual/cli/configuration/index.md
         - manual/cli/configuration/v2.md
         - manual/cli/configuration/v3.md
       - manual/cli/markers.md
