diff options
Diffstat (limited to 'man/asciinema.1')
| -rw-r--r-- | man/asciinema.1 | 403 |
1 files changed, 403 insertions, 0 deletions
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. |