diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:59:18 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:59:18 +0000 |
commit | fa60720fe95711a68dd4f1cb57fbc79fc6fc2e5c (patch) | |
tree | a8712923a49e76a6241f151af877900e056ce65d /man | |
parent | Initial commit. (diff) | |
download | asciinema-upstream/2.4.0.tar.xz asciinema-upstream/2.4.0.zip |
Adding upstream version 2.4.0.upstream/2.4.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man')
-rw-r--r-- | man/Makefile | 4 | ||||
-rw-r--r-- | man/asciinema.1 | 403 | ||||
-rw-r--r-- | man/asciinema.1.md | 345 |
3 files changed, 752 insertions, 0 deletions
diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 0000000..c635dfc --- /dev/null +++ b/man/Makefile @@ -0,0 +1,4 @@ +VERSION=`python3 -c "import asciinema; print(asciinema.__version__)"` + +asciinema.1: asciinema.1.md + pandoc asciinema.1.md -s -t man -o asciinema.1 -V header:"Version $(VERSION), `date +%Y-%m-%d`" diff --git a/man/asciinema.1 b/man/asciinema.1 new file mode 100644 index 0000000..6afa4c6 --- /dev/null +++ b/man/asciinema.1 @@ -0,0 +1,403 @@ +.\" Automatically generated by Pandoc 2.18 +.\" +.\" Define V font for inline verbatim, using C font in formats +.\" that render this, and otherwise B font. +.ie "\f[CB]x\f[]"x" \{\ +. ftr V B +. ftr VI BI +. ftr VB B +. ftr VBI BI +.\} +.el \{\ +. ftr V CR +. ftr VI CI +. ftr VB CB +. ftr VBI CBI +.\} +.TH "ASCIINEMA" "1" "" "Version 2.0.1" "Version 2.1.0, 2022-05-07" +.hy +.SH NAME +.PP +\f[B]asciinema\f[R] - terminal session recorder +.SH SYNOPSIS +.PP +\f[B]asciinema --version\f[R] +.PD 0 +.P +.PD +\f[B]asciinema\f[R] \f[I]command\f[R] [\f[I]options\f[R]] +[\f[I]args\f[R]] +.SH DESCRIPTION +.PP +asciinema lets you easily record terminal sessions, replay them in a +terminal as well as in a web browser and share them on the web. +asciinema is Free and Open Source Software licensed under the GNU +General Public License v3. +.SH COMMANDS +.PP +asciinema is composed of multiple commands, similar to \f[V]git\f[R], +\f[V]apt-get\f[R] or \f[V]brew\f[R]. +.PP +When you run \f[B]asciinema\f[R] with no arguments a help message is +displayed, listing all available commands with their options. +.SS rec [\f[I]filename\f[R]] +.PP +Record terminal session. +.PP +By running \f[B]asciinema rec [filename]\f[R] you start a new recording +session. +The command (process) that is recorded can be specified with +\f[B]-c\f[R] option (see below), and defaults to \f[B]$SHELL\f[R] which +is what you want in most cases. +.PP +You can temporarily pause recording of terminal by pressing Ctrl+\[rs]. +This is useful when you want to execute some commands during the +recording session that should not be captured (e.g.\ pasting secrets). +Resume by pressing Ctrl+\[rs] again. +.PP +Recording finishes when you exit the shell (hit Ctrl+D or type +\f[V]exit\f[R]). +If the recorded process is not a shell then recording finishes when the +process exits. +.PP +If the \f[I]filename\f[R] argument is omitted then (after asking for +confirmation) the resulting asciicast is uploaded to +asciinema-server (https://github.com/asciinema/asciinema-server) (by +default to asciinema.org), where it can be watched and shared. +.PP +If the \f[I]filename\f[R] argument is given then the resulting recording +(called asciicast) is saved to a local file. +It can later be replayed with \f[B]asciinema play <filename>\f[R] and/or +uploaded to asciinema server with \f[B]asciinema upload <filename>\f[R]. +.PP +\f[B]ASCIINEMA_REC=1\f[R] is added to recorded process environment +variables. +This can be used by your shell\[cq]s config file (\f[V].bashrc\f[R], +\f[V].zshrc\f[R]) to alter the prompt or play a sound when the shell is +being recorded. +.TP +Available options: +\ +.RS +.TP +\f[V]--stdin\f[R] +Enable stdin (keyboard) recording (see below) +.TP +\f[V]--append\f[R] +Append to existing recording +.TP +\f[V]--raw\f[R] +Save raw STDOUT output, without timing information or other metadata +.TP +\f[V]--overwrite\f[R] +Overwrite the recording if it already exists +.TP +\f[V]-c, --command=<command>\f[R] +Specify command to record, defaults to \f[B]$SHELL\f[R] +.TP +\f[V]-e, --env=<var-names>\f[R] +List of environment variables to capture, defaults to +\f[B]SHELL,TERM\f[R] +.TP +\f[V]-t, --title=<title>\f[R] +Specify the title of the asciicast +.TP +\f[V]-i, --idle-time-limit=<sec>\f[R] +Limit recorded terminal inactivity to max \f[V]<sec>\f[R] seconds +.TP +\f[V]--cols=<n>\f[R] +Override terminal columns for recorded process +.TP +\f[V]--rows=<n>\f[R] +Override terminal rows for recorded process +.TP +\f[V]-y, --yes\f[R] +Answer \[lq]yes\[rq] to all prompts (e.g.\ upload confirmation) +.TP +\f[V]-q, --quiet\f[R] +Be quiet, suppress all notices/warnings (implies \f[B]-y\f[R]) +.RE +.PP +Stdin recording allows for capturing of all characters typed in by the +user in the currently recorded shell. +This may be used by a player (e.g. +asciinema-player (https://github.com/asciinema/asciinema-player)) to +display pressed keys. +Because it\[cq]s basically a key-logging (scoped to a single shell +instance), it\[cq]s disabled by default, and has to be explicitly +enabled via \f[B]\[en]stdin\f[R] option. +.SS play <\f[I]filename\f[R]> +.PP +Replay recorded asciicast in a terminal. +.PP +This command replays a given asciicast (as recorded by \f[B]rec\f[R] +command) directly in your terminal. +The asciicast can be read from a file or from \f[I]\f[VI]stdin\f[I]\f[R] +(`-'): +.PP +Playing from a local file: +.IP +.nf +\f[C] +asciinema play /path/to/asciicast.cast +\f[R] +.fi +.PP +Playing from HTTP(S) URL: +.IP +.nf +\f[C] +asciinema play https://asciinema.org/a/22124.cast +asciinema play http://example.com/demo.cast +\f[R] +.fi +.PP +Playing from asciicast page URL (requires +\f[V]<link rel=\[dq]alternate\[dq] type=\[dq]application/x-asciicast\[dq] href=\[dq]/my/ascii.cast\[dq]>\f[R] +in page\[cq]s HTML): +.IP +.nf +\f[C] +asciinema play https://asciinema.org/a/22124 +asciinema play http://example.com/blog/post.html +\f[R] +.fi +.PP +Playing from stdin: +.IP +.nf +\f[C] +cat /path/to/asciicast.cast | asciinema play - +ssh user\[at]host cat asciicast.cast | asciinema play - +\f[R] +.fi +.PP +Playing from IPFS: +.IP +.nf +\f[C] +asciinema play dweb:/ipfs/QmNe7FsYaHc9SaDEAEXbaagAzNw9cH7YbzN4xV7jV1MCzK/ascii.cast +\f[R] +.fi +.TP +Available options: +\ +.RS +.TP +\f[V]-i, --idle-time-limit=<sec>\f[R] +Limit replayed terminal inactivity to max \f[V]<sec>\f[R] seconds (can +be fractional) +.TP +\f[V]-s, --speed=<factor>\f[R] +Playback speed (can be fractional) +.RE +.TP +While playing the following keyboard shortcuts are available: +\ +.RS +.TP +\f[I]\f[VI]Space\f[I]\f[R] +Toggle pause +.TP +\f[I]\f[VI].\f[I]\f[R] +Step through a recording a frame at a time (when paused) +.TP +\f[I]\f[VI]Ctrl+C\f[I]\f[R] +Exit +.RE +.PP +Recommendation: run `asciinema play' in a terminal of dimensions not +smaller than the one used for recording as there\[cq]s no +\[lq]transcoding\[rq] of control sequences for the new terminal size. +.SS cat <\f[I]filename\f[R]> +.PP +Print full output of recorded asciicast to a terminal. +.PP +While \f[B]asciinema play \f[R] replays the recorded session using +timing information saved in the asciicast, \f[B]asciinema cat \f[R] +dumps the full output (including all escape sequences) to a terminal +immediately. +.PP +\f[B]asciinema cat existing.cast >output.txt\f[R] gives the same result +as recording via \f[B]asciinema rec --raw output.txt\f[R]. +.SS upload <\f[I]filename\f[R]> +.PP +Upload recorded asciicast to asciinema.org site. +.PP +This command uploads given asciicast (recorded by \f[B]rec\f[R] command) +to asciinema.org, where it can be watched and shared. +.PP +\f[B]asciinema rec demo.cast\f[R] + \f[B]asciinema play demo.cast\f[R] + +\f[B]asciinema upload demo.cast\f[R] is a nice combo if you want to +review an asciicast before publishing it on asciinema.org. +.SS auth +.PP +Link and manage your install ID with your asciinema.org user account. +.PP +If you want to manage your recordings (change title/theme, delete) at +asciinema.org you need to link your \[lq]install ID\[rq] with your +asciinema.org user account. +.PP +This command displays the URL to open in a web browser to do that. +You may be asked to log in first. +.PP +Install ID is a random ID (UUID +v4 (https://en.wikipedia.org/wiki/Universally_unique_identifier)) +generated locally when you run asciinema for the first time, and saved +at \f[B]$HOME/.config/asciinema/install-id\f[R]. +It\[cq]s purpose is to connect local machine with uploaded recordings, +so they can later be associated with asciinema.org account. +This way we decouple uploading from account creation, allowing them to +happen in any order. +.PP +Note: A new install ID is generated on each machine and system user +account you use asciinema on. +So in order to keep all recordings under a single asciinema.org account +you need to run \f[B]asciinema auth\f[R] on all of those machines. +If you\[cq]re already logged in on asciinema.org website and you run +`asciinema auth' from a new computer then this new device will be linked +to your account. +.PP +While you CAN synchronize your config file (which keeps the API token) +across all your machines so all use the same token, that\[cq]s not +necessary. +You can assign new tokens to your account from as many machines as you +want. +.PP +Note: asciinema versions prior to 2.0 confusingly referred to install ID +as \[lq]API token\[rq]. +.SH EXAMPLES +.PP +Record your first session: +.IP +.nf +\f[C] +asciinema rec first.cast +\f[R] +.fi +.PP +End your session: +.IP +.nf +\f[C] +exit +\f[R] +.fi +.PP +Now replay it with double speed: +.IP +.nf +\f[C] +asciinema play -s 2 first.cast +\f[R] +.fi +.PP +Or with normal speed but with idle time limited to 2 seconds: +.IP +.nf +\f[C] +asciinema play -i 2 first.cast +\f[R] +.fi +.PP +You can pass \f[B]-i 2\f[R] to \f[B]asciinema rec\f[R] as well, to set +it permanently on a recording. +Idle time limiting makes the recordings much more interesting to watch, +try it. +.PP +If you want to watch and share it on the web, upload it: +.IP +.nf +\f[C] +asciinema upload first.cast +\f[R] +.fi +.PP +The above uploads it to <https://asciinema.org>, which is a default +asciinema-server (<https://github.com/asciinema/asciinema-server>) +instance, and prints a secret link you can use to watch your recording +in a web browser. +.PP +You can record and upload in one step by omitting the filename: +.IP +.nf +\f[C] +asciinema rec +\f[R] +.fi +.PP +You\[cq]ll be asked to confirm the upload when the recording is done, so +nothing is sent anywhere without your consent. +.SS Tricks +.TP +Record slowly, play faster: +First record a session where you can take your time to type slowly what +you want to show in the recording: +.RS +.IP +.nf +\f[C] +asciinema rec initial.cast +\f[R] +.fi +.PP +Then record the replay of `initial.cast' as `final.cast', but with five +times the initially recorded speed, with all pauses capped to two +seconds and with a title set as \[lq]My fancy title\[rq]:: +.IP +.nf +\f[C] +asciinema rec -c \[dq]asciinema play -s 5 -i 2 initial.cast\[dq] -t \[dq]My fancy title\[dq] final.cast +\f[R] +.fi +.RE +.TP +Play from \f[I]\f[VI]stdin\f[I]\f[R]: +\ +.RS +.PP +cat /path/to/asciicast.json | asciinema play - +.RE +.TP +Play file from remote host accessible with SSH: +\ +.RS +.PP +ssh user\[at]host cat /path/to/asciicat.json | asciinema play - +.RE +.SH ENVIRONMENT +.TP +\f[B]ASCIINEMA_API_URL\f[R] +This variable allows overriding asciinema-server URL (which defaults to +https://asciinema.org) in case you\[cq]re running your own +asciinema-server instance. +.TP +\f[B]ASCIINEMA_CONFIG_HOME\f[R] +This variable allows overriding config directory location. +Default location is $XDG_CONFIG_HOME/asciinema (when $XDG_CONFIG_HOME is +set) or $HOME/.config/asciinema. +.SH BUGS +.PP +See GitHub Issues: <https://github.com/asciinema/asciinema/issues> +.SH MORE RESOURCES +.PP +More documentation is available on the asciicast.org website and its +GitHub wiki: +.IP \[bu] 2 +Web: asciinema.org/docs/ (https://asciinema.org/docs/) +.IP \[bu] 2 +Wiki: +github.com/asciinema/asciinema/wiki (https://github.com/asciinema/asciinema/wiki) +.IP \[bu] 2 +IRC: Channel on Libera.Chat (https://web.libera.chat/gamja/#asciinema) +.IP \[bu] 2 +Twitter: \[at]asciinema (https://twitter.com/asciinema) +.SH AUTHORS +.PP +asciinema\[cq]s lead developer is Marcin Kulik. +.PP +For a list of all contributors look here: +<https://github.com/asciinema/asciinema/contributors> +.PP +This Manual Page was written by Marcin Kulik with help from Kurt +Pfeifle. diff --git a/man/asciinema.1.md b/man/asciinema.1.md new file mode 100644 index 0000000..54e1aa1 --- /dev/null +++ b/man/asciinema.1.md @@ -0,0 +1,345 @@ +% ASCIINEMA(1) Version 2.0.1 | asciinema + + +NAME +==== + +**asciinema** - terminal session recorder + + +SYNOPSIS +======== + +| **asciinema \-\-version** +| **asciinema** _command_ \[_options_] \[_args_] + + +DESCRIPTION +=========== + +asciinema lets you easily record terminal sessions, replay +them in a terminal as well as in a web browser and share them on the web. +asciinema is Free and Open Source Software licensed under +the GNU General Public License v3. + + +COMMANDS +======== + +asciinema is composed of multiple commands, similar to `git`, `apt-get` or +`brew`. + +When you run **asciinema** with no arguments a help message is displayed, listing +all available commands with their options. + + +rec [_filename_] +--- + +Record terminal session. + +By running **asciinema rec [filename]** you start a new recording session. The +command (process) that is recorded can be specified with **-c** option (see +below), and defaults to **$SHELL** which is what you want in most cases. + +You can temporarily pause the capture of your terminal by pressing +<kbd>Ctrl+\\</kbd>. This is useful when you want to execute some commands during +the recording session that should not be captured (e.g. pasting secrets). Resume +by pressing <kbd>Ctrl+\\</kbd> again. When pausing desktop notification is +displayed so you're sure the sensitive output won't be captured in the +recording. + +Recording finishes when you exit the shell (hit <kbd>Ctrl+D</kbd> or type +`exit`). If the recorded process is not a shell then recording finishes when +the process exits. + +If the _filename_ argument is omitted then (after asking for confirmation) the +resulting asciicast is uploaded to +[asciinema-server](https://github.com/asciinema/asciinema-server) (by default to +asciinema.org), where it can be watched and shared. + +If the _filename_ argument is given then the resulting recording (called +[asciicast](doc/asciicast-v2.md)) is saved to a local file. It can later be +replayed with **asciinema play \<filename>** and/or uploaded to asciinema server +with **asciinema upload \<filename>**. + +**ASCIINEMA_REC=1** is added to recorded process environment variables. This +can be used by your shell's config file (`.bashrc`, `.zshrc`) to alter the +prompt or play a sound when the shell is being recorded. + +Available options: + +: + + `--stdin` + : Enable stdin (keyboard) recording (see below) + + `--append` + : Append to existing recording + + `--raw` + : Save raw STDOUT output, without timing information or other metadata + + `--overwrite` + : Overwrite the recording if it already exists + + `-c, --command=<command>` + : Specify command to record, defaults to **$SHELL** + + `-e, --env=<var-names>` + : List of environment variables to capture, defaults to **SHELL,TERM** + + `-t, --title=<title>` + : Specify the title of the asciicast + + `-i, --idle-time-limit=<sec>` + : Limit recorded terminal inactivity to max `<sec>` seconds + + `--cols=<n>` + : Override terminal columns for recorded process + + `--rows=<n>` + : Override terminal rows for recorded process + + `-y, --yes` + : Answer "yes" to all prompts (e.g. upload confirmation) + + `-q, --quiet` + : Be quiet, suppress all notices/warnings (implies **-y**) + +Stdin recording allows for capturing of all characters typed in by the user in +the currently recorded shell. This may be used by a player (e.g. +[asciinema-player](https://github.com/asciinema/asciinema-player)) to display +pressed keys. Because it's basically a key-logging (scoped to a single shell +instance), it's disabled by default, and has to be explicitly enabled via +**--stdin** option. + + +play <_filename_> +--- + +Replay recorded asciicast in a terminal. + +This command replays a given asciicast (as recorded by **rec** command) directly in +your terminal. The asciicast can be read from a file or from *`stdin`* ('-'): + +Playing from a local file: + + asciinema play /path/to/asciicast.cast + +Playing from HTTP(S) URL: + + asciinema play https://asciinema.org/a/22124.cast + asciinema play http://example.com/demo.cast + +Playing from asciicast page URL (requires `<link rel="alternate" +type="application/x-asciicast" href="/my/ascii.cast">` in page's HTML): + + asciinema play https://asciinema.org/a/22124 + asciinema play http://example.com/blog/post.html + +Playing from stdin: + + cat /path/to/asciicast.cast | asciinema play - + ssh user@host cat asciicast.cast | asciinema play - + +Playing from IPFS: + + asciinema play dweb:/ipfs/QmNe7FsYaHc9SaDEAEXbaagAzNw9cH7YbzN4xV7jV1MCzK/ascii.cast + +Available options: + +: + + `-i, --idle-time-limit=<sec>` + : Limit replayed terminal inactivity to max `<sec>` seconds (can be fractional) + + `-s, --speed=<factor>` + : Playback speed (can be fractional) + +While playing the following keyboard shortcuts are available: + +: + + *`Space`* + : Toggle pause + + *`.`* + : Step through a recording a frame at a time (when paused) + + *`Ctrl+C`* + : Exit + +Recommendation: run 'asciinema play' in a terminal of dimensions not smaller than the one +used for recording as there's no "transcoding" of control sequences for the new terminal +size. + + +cat <_filename_> +--- + +Print full output of recorded asciicast to a terminal. + +While **asciinema play <filename>** replays the recorded session using timing +information saved in the asciicast, **asciinema cat <filename>** dumps the full +output (including all escape sequences) to a terminal immediately. + +**asciinema cat existing.cast >output.txt** gives the same result as recording via +**asciinema rec \-\-raw output.txt**. + + +upload <_filename_> +------ + +Upload recorded asciicast to asciinema.org site. + +This command uploads given asciicast (recorded by **rec** command) to +asciinema.org, where it can be watched and shared. + +**asciinema rec demo.cast** + **asciinema play demo.cast** + **asciinema upload +demo.cast** is a nice combo if you want to review an asciicast before +publishing it on asciinema.org. + +auth +---- + +Link and manage your install ID with your asciinema.org user account. + +If you want to manage your recordings (change title/theme, delete) at +asciinema.org you need to link your "install ID" with your asciinema.org user +account. + +This command displays the URL to open in a web browser to do that. You may be +asked to log in first. + +Install ID is a random ID ([UUID +v4](https://en.wikipedia.org/wiki/Universally_unique_identifier)) generated +locally when you run asciinema for the first time, and saved at +**$HOME/.config/asciinema/install-id**. It's purpose is to connect local machine +with uploaded recordings, so they can later be associated with asciinema.org +account. This way we decouple uploading from account creation, allowing them to +happen in any order. + +Note: A new install ID is generated on each machine and system user account you use +asciinema on. So in order to keep all recordings under a single asciinema.org +account you need to run **asciinema auth** on all of those machines. If you’re +already logged in on asciinema.org website and you run 'asciinema auth' from a new +computer then this new device will be linked to your account. + +While you CAN synchronize your config file (which keeps the API token) across +all your machines so all use the same token, that’s not necessary. You can assign +new tokens to your account from as many machines as you want. + +Note: asciinema versions prior to 2.0 confusingly referred to install ID as "API +token". + + +EXAMPLES +======== + +Record your first session: + + asciinema rec first.cast + +End your session: + + exit + +Now replay it with double speed: + + asciinema play -s 2 first.cast + +Or with normal speed but with idle time limited to 2 seconds: + + asciinema play -i 2 first.cast + +You can pass **-i 2** to **asciinema rec** as well, to set it permanently on a +recording. Idle time limiting makes the recordings much more interesting to +watch, try it. + +If you want to watch and share it on the web, upload it: + + asciinema upload first.cast + +The above uploads it to <https://asciinema.org>, which is a +default asciinema-server (<https://github.com/asciinema/asciinema-server>) +instance, and prints a secret link you can use to watch your recording in a web +browser. + +You can record and upload in one step by omitting the filename: + + asciinema rec + +You'll be asked to confirm the upload when the recording is done, so nothing is +sent anywhere without your consent. + + +Tricks +------ + +Record slowly, play faster: + +: First record a session where you can take your time to type slowly what you want + to show in the recording: + + asciinema rec initial.cast + + Then record the replay of 'initial.cast' as 'final.cast', but with five times the + initially recorded speed, with all pauses capped to two seconds and with a title + set as "My fancy title":: + + asciinema rec -c "asciinema play -s 5 -i 2 initial.cast" -t "My fancy title" final.cast + +Play from *`stdin`*: + +: + + cat /path/to/asciicast.json | asciinema play - + +Play file from remote host accessible with SSH: + +: + + ssh user@host cat /path/to/asciicat.json | asciinema play - + + +ENVIRONMENT +=========== + +**ASCIINEMA_API_URL** + +: This variable allows overriding asciinema-server URL (which defaults to + https://asciinema.org) in case you're running your own asciinema-server instance. + +**ASCIINEMA_CONFIG_HOME** + +: This variable allows overriding config directory location. Default location + is $XDG\_CONFIG\_HOME/asciinema (when $XDG\_CONFIG\_HOME is set) + or $HOME/.config/asciinema. + + +BUGS +==== + +See GitHub Issues: <https://github.com/asciinema/asciinema/issues> + + +MORE RESOURCES +=============== + +More documentation is available on the asciicast.org website and its GitHub wiki: + +* Web: [asciinema.org/docs/](https://asciinema.org/docs/) +* Wiki: [github.com/asciinema/asciinema/wiki](https://github.com/asciinema/asciinema/wiki) +* IRC: [Channel on Libera.Chat](https://web.libera.chat/gamja/#asciinema) +* Twitter: [@asciinema](https://twitter.com/asciinema) + + +AUTHORS +======= + +asciinema's lead developer is Marcin Kulik. + +For a list of all contributors look here: <https://github.com/asciinema/asciinema/contributors> + +This Manual Page was written by Marcin Kulik with help from Kurt Pfeifle. |