Skip to content

Commit e08ec88

Browse files
ygelfandygelfand
committed
docs: update config doc
Signed-off-by: ygelfand <yuri@shlitz.com>
1 parent 4acf671 commit e08ec88

File tree

4 files changed

+163
-5
lines changed

4 files changed

+163
-5
lines changed

‎docs/content/_meta.js‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
export default {
2+
index: 'Overview',
3+
'user-guide': {
4+
type: 'separator',
5+
title: 'User Guide'
6+
},
7+
tui: 'TUI Guide',
8+
config: 'Configuration',
9+
'reference': {
10+
type: 'separator',
11+
title: 'Reference'
12+
},
13+
cli: 'CLI Reference'
14+
}

‎docs/content/_meta.json‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/content/cli/_meta.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
export default {
2+
'plexctl': 'plexctl Root',
3+
'*': {
4+
theme: {
5+
breadcrumb: true,
6+
pagination: true
7+
}
8+
}
9+
}

‎docs/content/config.mdx‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Configuration Reference
2+
3+
`plexctl` stores its configuration in a YAML file at `~/.plexctl.yaml`. While many of these settings are managed through the TUI (pressing `s` or `l`), you can gain granular control by editing the file directly.
4+
5+
## Full Example
6+
7+
```yaml
8+
token: "your_plex_token"
9+
output: "table" # Default: table
10+
verbose: 0 # Default: 0
11+
theme: "nord" # Default: default
12+
icon_type: "nerdfonts" # Default: emoji (detected)
13+
library_name_format: "icon_name" # Default: icon_name
14+
default_view_mode: "poster" # Default: poster
15+
close_video_on_quit: true # Default: false
16+
cache_dir: "/home/user/.plexctl/cache" # Default: ~/.plexctl/cache
17+
default_server: "d9e8f7a6b5c4d3e2f1a0"
18+
servers:
19+
"d9e8f7a6b5c4d3e2f1a0":
20+
name: "Main Server"
21+
url: "https://192-168-1-100.plex.direct:32400"
22+
libraries:
23+
order:
24+
- "1" # Movies
25+
- "4" # 4K Movies
26+
- "2" # TV Shows
27+
- "5" # Music
28+
settings:
29+
"1":
30+
icon_emoji: "🎬"
31+
icon_nf: "󰿎"
32+
hidden: false # Default: false
33+
view_mode: "poster" # Default: poster
34+
```
35+
36+
---
37+
38+
## UI Settings
39+
40+
Options that modify the look and feel of the Terminal User Interface.
41+
42+
### `theme`
43+
The color palette used by the TUI. `plexctl` includes several built-in themes.
44+
- **Default:** `default`
45+
- **Supported:** `nord`, `dracula`, `solarized-dark`, `solarized-light`, `gruvbox`, `catppuccin`.
46+
47+
### `icon_type`
48+
Sets the global icon set for the application.
49+
- **Default:** `emoji` (Auto-detected if possible)
50+
- **Options:**
51+
- `nerdfonts`: High-detail icons. Requires a terminal font from [Nerd Fonts](https://www.nerdfonts.com/).
52+
- `emoji`: Standard color emojis. Works in most modern terminal emulators.
53+
- `ascii`: Simple text-based icons (e.g., `[M]`, `[S]`). Best for maximum compatibility.
54+
55+
### `library_name_format`
56+
Controls the layout of the sidebar items.
57+
- **Default:** `icon_name`
58+
- **Options:**
59+
- `icon_name`: `🎬 Movies`
60+
- `name_icon`: `Movies 🎬`
61+
- `icon_only`: `🎬`
62+
- `name`: `Movies`
63+
64+
### `default_view_mode`
65+
The initial layout used when browsing a library.
66+
- **Default:** `poster`
67+
- **Options:** `poster` (grid), `list` (table).
68+
69+
---
70+
71+
## Playback & Cache
72+
73+
Settings related to how media is played and how data is stored locally.
74+
75+
### `close_video_on_quit`
76+
When exiting `plexctl`, determine if the `mpv` video window should also be closed.
77+
- **Default:** `false`
78+
- `true`: `plexctl` sends a quit command to `mpv` on exit.
79+
- `false`: `mpv` remains open and continues playing.
80+
81+
### `cache_dir`
82+
The filesystem path where search indexes, metadata, and images are cached to improve performance.
83+
- **Default:** `~/.plexctl/cache`
84+
85+
---
86+
87+
## Server Management
88+
89+
The `servers` key is a map of Plex Server configurations, indexed by their unique **ClientIdentifier**. These settings are typically **configured automatically** during the `plexctl login` or discovery process, but can be manually adjusted.
90+
91+
### `default_server`
92+
Contains the ClientIdentifier of the server that `plexctl` should connect to by default when starting.
93+
94+
### `servers.[ID].name`
95+
A user-defined alias for the server, used in server selection menus.
96+
97+
### `servers.[ID].url`
98+
The base URL used to reach the server. For remote or secure access, this is typically the `.plex.direct` address.
99+
100+
---
101+
102+
## Library Overrides
103+
104+
The `libraries` section within a server allows you to customize individual library sections.
105+
106+
### `order`
107+
A list of library keys (as strings) that defines the exact order they appear in the TUI sidebar.
108+
- In the example above, **Movies (1)** and **4K Movies (4)** are prioritized at the top.
109+
- Libraries **not** present in this list will be appended to the end in their default Plex order.
110+
111+
### `settings.[ID].hidden`
112+
When `true`, the library is completely hidden from the TUI sidebar.
113+
- **Default:** `false`
114+
115+
### `settings.[ID].icon_emoji` / `icon_nf` / `icon_ascii`
116+
Define custom icons for a specific library. `plexctl` will automatically use the value matching your global `icon_type`.
117+
118+
### `settings.[ID].view_mode`
119+
Force a specific view mode (`list` or `poster`) for this library, overriding the global `default_view_mode`.
120+
- **Default:** Inherits from `default_view_mode`.
121+
122+
---
123+
124+
## TUI Configuration
125+
126+
While you can edit `~/.plexctl.yaml` manually, most common settings can be managed directly within the `plexctl` TUI using dedicated configuration overlays.
127+
128+
### Global Settings (`s`)
129+
Pressing **`s`** at any time opens the Global Settings overlay. From here you can:
130+
- **Change Theme:** Cycle through available color palettes (Nord, Dracula, etc.) and see changes instantly.
131+
- **Set Icon Type:** Switch between Nerd Fonts, Emojis, and ASCII icons.
132+
- **Sidebar Layout:** Adjust the `library_name_format` to show or hide icons and names.
133+
134+
### Library Management (`l`)
135+
Pressing **`l`** opens the Library Configuration overlay. This allows you to manage the appearance of your sidebar:
136+
- **Hide Libraries:** Toggle the visibility of specific libraries (e.g., hide a "Photos" or "Home Movies" section).
137+
- **Custom Icons:** Browse and pick icons for each specific library using an integrated icon picker (supports Emoji and Nerd Fonts).
138+
- **Reorder Sidebar:** Use **`K`** and **`J`** (Shift+Up/Down) to drag and drop libraries into your preferred order.
139+
140+
Changes made in these overlays are saved immediately to your `.plexctl.yaml` file.

0 commit comments

Comments
 (0)