1ASCIINEMA(1) asciinema 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 and replay them in a
14 terminal as well as in a web browser.
15
17 asciinema is composed of multiple commands, similar to git, apt-get or
18 brew.
19 When you run asciinema with no arguments help message is displayed,
21 listing all available commands with their options.
22 rec [filename]
24 Record terminal session.
25 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 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 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 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 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 Available options:
50 --stdin
53 Enable stdin (keyboard) recording (see below)
54 --append
56 Append to existing recording
57 --raw Save raw STDOUT output, without timing information or
59 other metadata
60 --overwrite
62 Overwrite the recording if it already exists
63 -c, --command=<command>
65 Specify command to record, defaults to $SHELL
66 -e, --env=<var-names>
68 List of environment variables to capture, defaults to
69 SHELL,TERM
70 -t, --title=<title>
72 Specify the title of the asciicast
73 -i, --idle-time-limit=<sec>
75 Limit recorded terminal inactivity to max <sec> seconds
76 -y, --yes
78 Answer “yes” to all prompts (e.g. upload confirmation)
79 -q, --quiet
81 Be quiet, suppress all notices/warnings (implies -y)
82 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 play <filename>
91 Replay recorded asciicast in a terminal.
92 This command replays given asciicast (as recorded by rec command) di‐
94 rectly in your terminal.
95 Following keyboard shortcuts are available:
97 Space - toggle pause,
99 . - step through a recording a frame at a time (when paused),
100 Ctrl+C - exit.
101 Playing from a local file:
103 asciinema play /path/to/asciicast.cast
105 Playing from HTTP(S) URL:
107 asciinema play https://asciinema.org/a/22124.cast
109 asciinema play http://example.com/demo.cast
110 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 asciinema play https://asciinema.org/a/22124
116 asciinema play http://example.com/blog/post.html
117 Playing from stdin:
119 cat /path/to/asciicast.cast | asciinema play -
121 ssh user@host cat asciicast.cast | asciinema play -
122 Playing from IPFS:
124 asciinema play dweb:/ipfs/QmNe7FsYaHc9SaDEAEXbaagAzNw9cH7YbzN4xV7jV1MCzK/ascii.cast
126 Available options:
128 -i, --idle-time-limit=<sec>
131 Limit replayed terminal inactivity to max <sec> seconds
132 -s, --speed=<factor>
134 Playback speed (can be fractional)
135 cat <filename>
137 Print full output of recorded asciicast to a terminal.
138 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 asciinema cat existing.cast >output.txt gives the same result as
144 recording via asciinema rec --raw output.txt.
145 upload
147 Upload recorded asciicast to asciinema.org site.
148 This command uploads given asciicast (recorded by rec command) to asci‐
150 inema.org, where it can be watched and shared.
151 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 auth
157 Link your install ID with your asciinema.org user account.
158 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 This command displays the URL to open in a web browser to do that. You
164 may be asked to log in first.
165 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 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 Note: asciinema versions prior to 2.0 confusingly referred to install
180 ID as “API token”.
181
183 Record your first session:
184 asciinema rec first.cast
186 Now replay it with double speed:
188 asciinema play -s 2 first.cast
190 Or with normal speed but with idle time limited to 2 seconds:
192 asciinema play -i 2 first.cast
194 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 If you want to watch and share it on the web, upload it:
200 asciinema upload first.cast
202 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 You can record and upload in one step by omitting the filename:
209 asciinema rec
211 You'll be asked to confirm the upload when the recording is done, so
213 nothing is sent anywhere without your consent.
214
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 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
227 See GitHub Issues: <https://github.com/asciinema/asciinema/issues>
228
230 asciinema's lead developer is Marcin Kulik.
231 For a list of all contributors look here: <https://github.com/asciine‐
233 ma/asciinema/contributors>
234 This Manual Page was written by Marcin Kulik with help from Kurt Pfei‐
236 fle.
237Version 2.0.1 ASCIINEMA(1)