1ASCIINEMA(1)                       asciinema                      ASCIINEMA(1)
2
3
4

NAME

6       asciinema - terminal session recorder
7

SYNOPSIS

9       asciinema --version
10       asciinema command [options] [args]
11

DESCRIPTION

13       asciinema lets you easily record terminal sessions and replay them in a
14       terminal as well as in a web browser.
15

COMMANDS

17       asciinema is composed of multiple commands, similar to git, apt-get  or
18       brew.
19
20       When  you  run  asciinema  with no arguments help message is displayed,
21       listing all available commands with their options.
22
23   rec [filename]
24       Record terminal session.
25
26       By running asciinema rec [filename] you start a new recording  session.
27       The  command (process) that is recorded can be specified with -c option
28       (see below), and defaults to $SHELL which is what you want in most cas‐
29       es.
30
31       Recording  finishes  when you exit the shell (hit Ctrl+D or type exit).
32       If the recorded process is not a shell then recording finishes when the
33       process exits.
34
35       If  the  filename  argument is omitted then (after asking for confirma‐
36       tion)  the  resulting  asciicast  is   uploaded   to   asciinema-server
37       (https://github.com/asciinema/asciinema-server) (by default to asciine‐
38       ma.org), where it can be watched and shared.
39
40       If the filename argument is given then the resulting recording  (called
41       asciicast (doc/asciicast-v2.md)) is saved to a local file.  It can lat‐
42       er be replayed with asciinema play <filename> and/or uploaded to  asci‐
43       inema server with asciinema upload <filename>.
44
45       ASCIINEMA_REC=1  is  added  to  recorded process environment variables.
46       This can be used by your shell's config file (.bashrc, .zshrc) to alter
47       the prompt or play a sound when the shell is being recorded.
48
49       Available options:
50
51
52              --stdin
53                     Enable stdin (keyboard) recording (see below)
54
55              --append
56                     Append to existing recording
57
58              --raw  Save  raw  STDOUT  output,  without timing information or
59                     other metadata
60
61              --overwrite
62                     Overwrite the recording if it already exists
63
64              -c, --command=<command>
65                     Specify command to record, defaults to $SHELL
66
67              -e, --env=<var-names>
68                     List of environment variables  to  capture,  defaults  to
69                     SHELL,TERM
70
71              -t, --title=<title>
72                     Specify the title of the asciicast
73
74              -i, --idle-time-limit=<sec>
75                     Limit recorded terminal inactivity to max <sec> seconds
76
77              -y, --yes
78                     Answer “yes” to all prompts (e.g. upload confirmation)
79
80              -q, --quiet
81                     Be quiet, suppress all notices/warnings (implies -y)
82
83       Stdin  recording allows for capturing of all characters typed in by the
84       user in the currently recorded shell.  This may be  used  by  a  player
85       (e.g.   asciinema-player  (https://github.com/asciinema/asciinema-play
86       er)) to display pressed keys.  Because  it's  basically  a  key-logging
87       (scoped  to a single shell instance), it's disabled by default, and has
88       to be explicitly enabled via –stdin option.
89
90   play <filename>
91       Replay recorded asciicast in a terminal.
92
93       This command replays given asciicast (as recorded by rec  command)  di‐
94       rectly in your terminal.
95
96       Following keyboard shortcuts are available:
97
98              Space - toggle pause,
99              . - step through a recording a frame at a time (when paused),
100              Ctrl+C - exit.
101
102       Playing from a local file:
103
104              asciinema play /path/to/asciicast.cast
105
106       Playing from HTTP(S) URL:
107
108              asciinema play https://asciinema.org/a/22124.cast
109              asciinema play http://example.com/demo.cast
110
111       Playing   from   asciicast   page   URL   (requires   <link rel="alter‐
112       nate" type="application/x-asciicast" href="/my/ascii.cast">  in  page's
113       HTML):
114
115              asciinema play https://asciinema.org/a/22124
116              asciinema play http://example.com/blog/post.html
117
118       Playing from stdin:
119
120              cat /path/to/asciicast.cast | asciinema play -
121              ssh user@host cat asciicast.cast | asciinema play -
122
123       Playing from IPFS:
124
125              asciinema play dweb:/ipfs/QmNe7FsYaHc9SaDEAEXbaagAzNw9cH7YbzN4xV7jV1MCzK/ascii.cast
126
127       Available options:
128
129
130              -i, --idle-time-limit=<sec>
131                     Limit replayed terminal inactivity to max <sec> seconds
132
133              -s, --speed=<factor>
134                     Playback speed (can be fractional)
135
136   cat <filename>
137       Print full output of recorded asciicast to a terminal.
138
139       While  asciinema play  replays the recorded session using timing infor‐
140       mation saved in the asciicast, asciinema cat   dumps  the  full  output
141       (including all escape sequences) to a terminal immediately.
142
143       asciinema  cat  existing.cast  >output.txt  gives  the  same  result as
144       recording via asciinema rec --raw output.txt.
145
146   upload
147       Upload recorded asciicast to asciinema.org site.
148
149       This command uploads given asciicast (recorded by rec command) to asci‐
150       inema.org, where it can be watched and shared.
151
152       asciinema  rec  demo.cast + asciinema play demo.cast + asciinema upload
153       demo.cast is a nice combo if you want to  review  an  asciicast  before
154       publishing it on asciinema.org.
155
156   auth
157       Link your install ID with your asciinema.org user account.
158
159       If  you  want to manage your recordings (change title/theme, delete) at
160       asciinema.org you need to link your “install ID” with asciinema.org us‐
161       er account.
162
163       This command displays the URL to open in a web browser to do that.  You
164       may be asked to log in first.
165
166       Install ID is a random ID (UUID v4  (https://en.wikipedia.org/wiki/Uni
167       versally_unique_identifier))  generated  locally when you run asciinema
168       for the first time, and  saved  at  $HOME/.config/asciinema/install-id.
169       It's  purpose  is to connect local machine with uploaded recordings, so
170       they can later be associated with asciinema.org account.  This  way  we
171       decouple  uploading  from  account creation, allowing them to happen in
172       any order.
173
174       Note: A new install ID is generated on each machine and system user ac‐
175       count  you use asciinema on, so in order to keep all recordings under a
176       single asciinema.org account you need to run asciinema auth on  all  of
177       those machines.
178
179       Note:  asciinema  versions prior to 2.0 confusingly referred to install
180       ID as “API token”.
181

EXAMPLES

183       Record your first session:
184
185              asciinema rec first.cast
186
187       Now replay it with double speed:
188
189              asciinema play -s 2 first.cast
190
191       Or with normal speed but with idle time limited to 2 seconds:
192
193              asciinema play -i 2 first.cast
194
195       You can pass -i 2 to asciinema rec as well, to set it permanently on  a
196       recording.  Idle time limiting makes the recordings much more interest‐
197       ing to watch, try it.
198
199       If you want to watch and share it on the web, upload it:
200
201              asciinema upload first.cast
202
203       The above uploads it to <https://asciinema.org>,  which  is  a  default
204       asciinema-server  (<https://github.com/asciinema/asciinema-server>) in‐
205       stance, and prints a secret link you can use to watch your recording in
206       a web browser.
207
208       You can record and upload in one step by omitting the filename:
209
210              asciinema rec
211
212       You'll  be  asked  to confirm the upload when the recording is done, so
213       nothing is sent anywhere without your consent.
214

ENVIRONMENT

216       ASCIINEMA_API_URL
217              This variable allows overriding asciinema-server URL (which  de‐
218              faults to https://asciinema.org) in case you're running your own
219              asciinema-server instance.
220
221       ASCIINEMA_CONFIG_HOME
222              This variable allows overriding config directory location.   De‐
223              fault  location  is  $XDG_CONFIG_HOME/asciinema  (when $XDG_CON‐
224              FIG_HOME is set) or $HOME/.config/asciinema.
225

BUGS

227       See GitHub Issues: <https://github.com/asciinema/asciinema/issues>
228

AUTHORS

230       asciinema's lead developer is Marcin Kulik.
231
232       For a list of all contributors look here:  <https://github.com/asciine
233       ma/asciinema/contributors>
234
235       This  Manual Page was written by Marcin Kulik with help from Kurt Pfei‐
236       fle.
237
238
239
240Version 2.0.1                                                     ASCIINEMA(1)
Impressum