From 13c114b8fad9c0191cae263d597aeff0d9e4dfb6 Mon Sep 17 00:00:00 2001 From: Marcin Kulik Date: Thu, 12 Mar 2015 17:06:00 +0100 Subject: [PATCH] Update usage docs --- app/views/docs/usage.html.slim | 74 ++++++++++++++++++++++------------ 1 file changed, 49 insertions(+), 25 deletions(-) diff --git a/app/views/docs/usage.html.slim b/app/views/docs/usage.html.slim index 3f43722..d092f77 100644 --- a/app/views/docs/usage.html.slim +++ b/app/views/docs/usage.html.slim @@ -4,54 +4,78 @@ markdown: # Usage - asciinema cli is composed of multiple (sub)commands, similar to `git`, - `rails` or `brew`. + asciinema is composed of multiple commands, similar to `git`, `rails` or + `brew`. - If you run `asciinema` with no arguments, help will be displayed showing all - available commands. + When you run `asciinema` with no arguments help message is displayed showing + all available commands with their options. - In addition to this, you can run any asciinema command with the `-h` switch - to display help about that specific command. For example, try running - `asciinema rec -h`. This will display a list of all of the options `rec` - command accepts, with their defaults. + ## `rec [filename]` - ## `rec` - - __Record terminal session and upload it to asciinema.org site.__ + __Record terminal session.__ This is the single most important command in asciinema, since it is how you utilize this tool's main job. - By running `asciinema rec` 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. + 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. Recording finishes when you exit the shell (hit Ctrl+D or type - `exit`). If the recorded process is not a shell than recording finishes when + `exit`). If the recorded process is not a shell then recording finishes when the process exits. + If the `filename` argument is given then the resulting recording (called + [asciicast](doc/asciicast-v1.md)) is saved to a local file. It can later be + replayed with `asciinema play ` and/or uploaded to asciinema.org with + `asciinema upload `. If the `filename` argument is omitted then + (after asking for confirmation) the resulting asciicast is uploaded to + asciinema.org for further playback in a web browser. + `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 shell is being recorded. Available options: - * `-c` - command to record (if none given a new shell instance is recorded) - * `--max-wait` - reduce recorded terminal inactivity to maximum of seconds (0 turns off) - * `-t` - set asciicast title (can be also set later, on the site) - * `-y` - upload immediately after shell exits, without asking for confirmation + * `-c, --command=` - Specify command to record, defaults to $SHELL + * `-t, --title=` - Specify title of the asciicast + * `-w, --max-wait=<sec>` - Reduce recorded terminal inactivity to max <sec> seconds + * `-y, --yes` - Answer yes to all prompts (e.g. upload confirmation) + + ## `play <filename>` + + __Replay recorded asciicast in a terminal.__ + + This command replays given asciicast (as recorded by `rec` command) directly in + your terminal. + + NOTE: it is recommended to run it in a terminal of dimensions not smaller than + the one used for recording as there's no "transcoding" of control sequences for + new terminal size. + + ## `upload <filename>` + + __Upload recorded asciicast to asciinema.org site.__ + + This command uploads given asciicast (as recorded by `rec` command) to + asciinema.org for further playback in a web browser. + + `asciinema rec demo.json` + `asciinema play demo.json` + `asciinema upload + demo.json` is a nice combo for when you want to review an asciicast before + publishing it on asciinema.org. ## `auth` __Assign local API token to asciinema.org account.__ - Every machine you install asciinema recorder on you get a new unique API - token. This command is used to connect this local API token with your - asciinema.org account. + On every machine you install asciinema recorder, you get a new, unique API + token. This command connects this local token with your asciinema.org account, + and links all asciicasts recorded on this machine with the account. - This command displays the URL you should open in your web browser. If you - never logged in to asciinema.org then your account will be automatically - created when opening the URL. + This command displays the URL you should open in your web browser. If you never + logged in to asciinema.org then your account will be created when opening the + URL. NOTE: it is __necessary__ to do this if you want to __edit or delete__ your recordings on asciinema.org.