1ASCIINEMA(1) Version 2.1.0, 2022-05-07 ASCIINEMA(1)
2
6 asciinema - terminal session recorder
7
9 asciinema --version
10 asciinema command [options] [args]
11
13 asciinema lets you easily record terminal sessions, replay them in a
14 terminal as well as in a web browser and share them on the web. asci‐
15 inema is Free and Open Source Software licensed under the GNU General
16 Public License v3.
17
19 asciinema is composed of multiple commands, similar to git, apt-get or
20 brew.
21 When you run asciinema with no arguments a help message is displayed,
23 listing all available commands with their options.
24 rec [filename]
26 Record terminal session.
27 By running asciinema rec [filename] you start a new recording session.
29 The command (process) that is recorded can be specified with -c option
30 (see below), and defaults to $SHELL which is what you want in most cas‐
31 es.
32 You can temporarily pause recording of terminal by pressing Ctrl+\.
34 This is useful when you want to execute some commands during the
35 recording session that should not be captured (e.g. pasting secrets).
36 Resume by pressing Ctrl+\ again.
37 Recording finishes when you exit the shell (hit Ctrl+D or type exit).
39 If the recorded process is not a shell then recording finishes when the
40 process exits.
41 If the filename argument is omitted then (after asking for confirma‐
43 tion) the resulting asciicast is uploaded to asciinema-server
44 (https://github.com/asciinema/asciinema-server) (by default to asciine‐
45 ma.org), where it can be watched and shared.
46 If the filename argument is given then the resulting recording (called
48 asciicast) is saved to a local file. It can later be replayed with
49 asciinema play <filename> and/or uploaded to asciinema server with
50 asciinema upload <filename>.
51 ASCIINEMA_REC=1 is added to recorded process environment variables.
53 This can be used by your shell’s config file (.bashrc, .zshrc) to alter
54 the prompt or play a sound when the shell is being recorded.
55 Available options:
57 --stdin
59 Enable stdin (keyboard) recording (see below)
60 --append
62 Append to existing recording
63 --raw Save raw STDOUT output, without timing information or
65 other metadata
66 --overwrite
68 Overwrite the recording if it already exists
69 -c, --command=<command>
71 Specify command to record, defaults to $SHELL
72 -e, --env=<var-names>
74 List of environment variables to capture, defaults to
75 SHELL,TERM
76 -t, --title=<title>
78 Specify the title of the asciicast
79 -i, --idle-time-limit=<sec>
81 Limit recorded terminal inactivity to max <sec> seconds
82 --cols=<n>
84 Override terminal columns for recorded process
85 --rows=<n>
87 Override terminal rows for recorded process
88 -y, --yes
90 Answer “yes” to all prompts (e.g. upload confirmation)
91 -q, --quiet
93 Be quiet, suppress all notices/warnings (implies -y)
94 Stdin recording allows for capturing of all characters typed in by the
96 user in the currently recorded shell. This may be used by a player
97 (e.g. asciinema-player (https://github.com/asciinema/asciinema-play‐
98 er)) to display pressed keys. Because it’s basically a key-logging
99 (scoped to a single shell instance), it’s disabled by default, and has
100 to be explicitly enabled via –stdin option.
101 play <filename>
103 Replay recorded asciicast in a terminal.
104 This command replays a given asciicast (as recorded by rec command) di‐
106 rectly in your terminal. The asciicast can be read from a file or from
107 stdin (`-'):
108 Playing from a local file:
110 asciinema play /path/to/asciicast.cast
112 Playing from HTTP(S) URL:
114 asciinema play https://asciinema.org/a/22124.cast
116 asciinema play http://example.com/demo.cast
117 Playing from asciicast page URL (requires <link rel="alternate"
119 type="application/x-asciicast" href="/my/ascii.cast"> in page’s HTML):
120 asciinema play https://asciinema.org/a/22124
122 asciinema play http://example.com/blog/post.html
123 Playing from stdin:
125 cat /path/to/asciicast.cast | asciinema play -
127 ssh user@host cat asciicast.cast | asciinema play -
128 Playing from IPFS:
130 asciinema play dweb:/ipfs/QmNe7FsYaHc9SaDEAEXbaagAzNw9cH7YbzN4xV7jV1MCzK/ascii.cast
132 Available options:
134 -i, --idle-time-limit=<sec>
136 Limit replayed terminal inactivity to max <sec> seconds
137 (can be fractional)
138 -s, --speed=<factor>
140 Playback speed (can be fractional)
141 While playing the following keyboard shortcuts are available:
143 Space Toggle pause
145 . Step through a recording a frame at a time (when paused)
147 Ctrl+C Exit
149 Recommendation: run `asciinema play' in a terminal of dimensions not
151 smaller than the one used for recording as there’s no “transcoding” of
152 control sequences for the new terminal size.
153 cat <filename>
155 Print full output of recorded asciicast to a terminal.
156 While asciinema play replays the recorded session using timing infor‐
158 mation saved in the asciicast, asciinema cat dumps the full output (in‐
159 cluding all escape sequences) to a terminal immediately.
160 asciinema cat existing.cast >output.txt gives the same result as
162 recording via asciinema rec --raw output.txt.
163 upload <filename>
165 Upload recorded asciicast to asciinema.org site.
166 This command uploads given asciicast (recorded by rec command) to asci‐
168 inema.org, where it can be watched and shared.
169 asciinema rec demo.cast + asciinema play demo.cast + asciinema upload
171 demo.cast is a nice combo if you want to review an asciicast before
172 publishing it on asciinema.org.
173 auth
175 Link and manage your install ID with your asciinema.org user account.
176 If you want to manage your recordings (change title/theme, delete) at
178 asciinema.org you need to link your “install ID” with your asciine‐
179 ma.org user account.
180 This command displays the URL to open in a web browser to do that. You
182 may be asked to log in first.
183 Install ID is a random ID (UUID v4 (https://en.wikipedia.org/wiki/Uni‐
185 versally_unique_identifier)) generated locally when you run asciinema
186 for the first time, and saved at $HOME/.config/asciinema/install-id.
187 It’s purpose is to connect local machine with uploaded recordings, so
188 they can later be associated with asciinema.org account. This way we
189 decouple uploading from account creation, allowing them to happen in
190 any order.
191 Note: A new install ID is generated on each machine and system user ac‐
193 count you use asciinema on. So in order to keep all recordings under a
194 single asciinema.org account you need to run asciinema auth on all of
195 those machines. If you’re already logged in on asciinema.org website
196 and you run `asciinema auth' from a new computer then this new device
197 will be linked to your account.
198 While you CAN synchronize your config file (which keeps the API token)
200 across all your machines so all use the same token, that’s not neces‐
201 sary. You can assign new tokens to your account from as many machines
202 as you want.
203 Note: asciinema versions prior to 2.0 confusingly referred to install
205 ID as “API token”.
206
208 Record your first session:
209 asciinema rec first.cast
211 End your session:
213 exit
215 Now replay it with double speed:
217 asciinema play -s 2 first.cast
219 Or with normal speed but with idle time limited to 2 seconds:
221 asciinema play -i 2 first.cast
223 You can pass -i 2 to asciinema rec as well, to set it permanently on a
225 recording. Idle time limiting makes the recordings much more interest‐
226 ing to watch, try it.
227 If you want to watch and share it on the web, upload it:
229 asciinema upload first.cast
231 The above uploads it to <https://asciinema.org>, which is a default
233 asciinema-server (<https://github.com/asciinema/asciinema-server>) in‐
234 stance, and prints a secret link you can use to watch your recording in
235 a web browser.
236 You can record and upload in one step by omitting the filename:
238 asciinema rec
240 You’ll be asked to confirm the upload when the recording is done, so
242 nothing is sent anywhere without your consent.
243 Tricks
245 Record slowly, play faster:
246 First record a session where you can take your time to type
247 slowly what you want to show in the recording:
248 asciinema rec initial.cast
250 Then record the replay of `initial.cast' as `final.cast', but
252 with five times the initially recorded speed, with all pauses
253 capped to two seconds and with a title set as “My fancy title”::
254 asciinema rec -c "asciinema play -s 5 -i 2 initial.cast" -t "My fancy title" final.cast
256 Play from stdin:
258 cat /path/to/asciicast.json | asciinema play -
260 Play file from remote host accessible with SSH:
262 ssh user@host cat /path/to/asciicat.json | asciinema play -
264
266 ASCIINEMA_API_URL
267 This variable allows overriding asciinema-server URL (which de‐
268 faults to https://asciinema.org) in case you’re running your own
269 asciinema-server instance.
270 ASCIINEMA_CONFIG_HOME
272 This variable allows overriding config directory location. De‐
273 fault location is $XDG_CONFIG_HOME/asciinema (when $XDG_CON‐
274 FIG_HOME is set) or $HOME/.config/asciinema.
275
277 See GitHub Issues: <https://github.com/asciinema/asciinema/issues>
278
280 More documentation is available on the asciicast.org website and its
281 GitHub wiki:
282 • Web: asciinema.org/docs/ (https://asciinema.org/docs/)
284 • Wiki: github.com/asciinema/asciinema/wiki (https://github.com/asci‐
286 inema/asciinema/wiki)
287 • IRC: Channel on Libera.Chat (https://web.libera.chat/gamja/#asciine‐
289 ma)
290 • Twitter: @asciinema (https://twitter.com/asciinema)
292
294 asciinema’s lead developer is Marcin Kulik.
295 For a list of all contributors look here: <https://github.com/asciine‐
297 ma/asciinema/contributors>
298 This Manual Page was written by Marcin Kulik with help from Kurt Pfei‐
300 fle.
301Version 2.0.1 ASCIINEMA(1)