Mirrors/asciinema
1
0
Fork 0
mirror of https://github.com/asciinema/asciinema.git synced 2025-12-16 03:38:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Keep UUID out of config file and call it "install ID"

Browse Source 
We referred to this locally generated UUID as "API token" which was wrong,
because it doesn't have any special API powers, and is only used to link local
machine with uploaded recordings, so they can later be associated with
asciinema.org account.

It's more of device token or installation ID in nature, so let's call it
"install ID" for short, and keep it at ~/.config/asciinema/install-id.

Keeping it in automatically created config file also turned out to be not the
best idea - the config was mixing user preferences with local, device specific
state, preventing easy publishing of the config (for example in a public
dotfiles repository).
This commit is contained in:
Marcin Kulik
2017-12-04 00:25:50 +01:00
parent b7231c2872
commit 331dcf497f
6 changed files with 223 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
README.md
View File

@@ -253,19 +253,29 @@ publishing it on asciinema.org.
### `auth`
__Manage recordings on asciinema.org account.__
__Link your install ID with your asciinema.org user account.__
If you want to manage your recordings on asciinema.org (set title/description,
delete etc) you need to authenticate. This command displays the URL you should
open in your web browser to do that.
If you want to manage your recordings (change title/theme, delete) at
asciinema.org you need to link your "install ID" with asciinema.org user
account.
On every machine you run asciinema recorder, you get a new, unique API token. If
you'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.
This command displays the URL to open in a web browser to do that. You may be
asked to log in first.
You can synchronize your config file (which keeps the API token) across the
machines so all of them use the same token, but that's not necessary. You can
assign new tokens to your account from as many machines as you want.
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
`$HOME/.config/asciinema/install-id`. It'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.
> 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 `asciinema auth` on all of those machines.
> asciinema versions prior to 2.0 confusingly referred to install ID as "API
> token".
## Hosting the recordings on the web
@@ -287,87 +297,64 @@ If you prefer to host the recordings yourself, you can do so by either:
## Configuration file
asciinema uses a config file to keep API token and user settings. In most cases
the location of this file is `$HOME/.config/asciinema/config`.
You can configure asciinema by creating config file at
`$HOME/.config/asciinema/config`.
*NOTE: When you first run asciinema, local API token is generated (UUID) and
saved in the file (unless the file already exists or you have set
`ASCIINEMA_API_TOKEN` environment variable).*
The auto-generated, minimal config file looks like this:
```ini
[api]
token = <your-api-token-here>
```
There are several options you can set in this file. Here's a config with all
available options set:
Configuration is split into sections (`[api]`, `[record]`, `[play]`). Here's a
list of all available options for each section:
```ini
[api]
; API server URL, default: https://asciinema.org
; If you run your own instance of asciinema-server then set its address here
; It can also be overriden by setting ASCIINEMA_API_URL environment variable
url = https://asciinema.example.com
; API token, autogenerated when uploading a recording for the first time
token = <your-api-token-here>
[record]
; command to record, default: $SHELL
; Command to record, default: $SHELL
command = /bin/bash -l
; enable stdin (keyboard) recording, default: no
; Enable stdin (keyboard) recording, default: no
stdin = yes
; list of environment variables to capture, default: SHELL,TERM
; List of environment variables to capture, default: SHELL,TERM
env = SHELL,TERM,USER
; limit recorded terminal inactivity to max n seconds, default: off
; Limit recorded terminal inactivity to max n seconds, default: off
idle_time_limit = 2
; answer "yes" to all interactive prompts, default: no
; Answer "yes" to all interactive prompts, default: no
yes = true
; be quiet, suppress all notices/warnings, default: no
; Be quiet, suppress all notices/warnings, default: no
quiet = true
[play]
; playback speed (can be fractional), default: 1
; Playback speed (can be fractional), default: 1
speed = 2
; limit replayed terminal inactivity to max n seconds, default: off
; Limit replayed terminal inactivity to max n seconds, default: off
idle_time_limit = 1
```
The options in `[api]` section are related to API location and authentication.
To tell asciinema recorder to use your own asciinema server instance rather than
the default one (asciinema.org), you can set `url` option. API URL can also be
passed via `ASCIINEMA_API_URL` environment variable, and API token via
`ASCIINEMA_API_TOKEN` environment variable.
A very minimal config file could look like that:
The options in `[record]` and `[play]` sections have the same meaning as the
options you pass to `asciinema rec`/`asciinema play` command. If you happen to
often use either `-c`, `-i` or `-y` with these commands then consider saving it
as a default in the config file.
```ini
[record]
idle_time_limit = 2
```
> If you want to publish your asciinema config file (in public dotfiles
> repository) you __should__ remove `token = ...` line from the file and use
> `ASCIINEMA_API_TOKEN` environment variable instead.
Config file location can be changed by setting `$ASCIINEMA_CONFIG_HOME`
environment variable, which should point to a directory.
### Configuration file locations
If `$XDG_CONFIG_HOME` is set on Linux then asciinema uses
`$XDG_CONFIG_HOME/asciinema/config` instead of `$HOME/.config/asciinema/config`.
In fact, the following locations are checked for the presence of the config
file (in the given order):
* `$ASCIINEMA_CONFIG_HOME/config` - if you have set `$ASCIINEMA_CONFIG_HOME`
* `$XDG_CONFIG_HOME/asciinema/config` - on Linux, `$XDG_CONFIG_HOME` usually points to `$HOME/.config/`
* `$HOME/.config/asciinema/config` - in most cases it's here
* `$HOME/.asciinema/config` - created by asciinema versions prior to 1.1
The first one found is used.
> asciinema versions prior to 1.1 used `$HOME/.asciinema/config`. If you have it
> there you should `mv $HOME/.asciinema $HOME/.config/asciinema`.
## Contributing