TUI Dashboard¶

Type max on its own to open the interactive terminal dashboard. You can download media, run tools, watch the task queue, browse files, edit settings and chat with the AI from one screen.

Usage¶

max              # opens the dashboard
max dashboard    # the same, by name

A bare max opens the dashboard only when you run it in a terminal. In a script, a pipe or CI it prints the help text, so nothing waits for key presses.

The dashboard comes with the base install. Older instructions say pip install max-cli[tui]; that command still works.

Sections¶

The sidebar on the left lists eleven sections in three groups, each with its name. Press the « button at the top (or Ctrl+B) to fold it to a strip of icons; hover an icon to see its name, and press » to open it again. Press a section's key to jump to it (a number, or , for Settings), click it, or move with the arrow keys and press Enter. The dashboard opens on the section you used last.

Key	Section	What it does
	Do
`1`	Home	Launchpad and command center: ask Max in plain words, open any page, pick up the actions you use most, and see your week, your activity by type and what ran lately
`2`	Download	Download form with progress and recent downloads
`3`	Video	Pick a video or audio file, see its length, size and codecs, and run any `max video` action on it
`4`	Audio	Pick a song or a folder of music, see its tags, length and bitrate (or how many tracks lack tags), edit tags, sort music into folders, compress or clean it
`5`	Images	Pick an image or a folder, see its size in pixels, format, date and camera (or how many images a folder holds), and run any `max images` action on it
`6`	PDF	Pick a PDF, see its pages, paper size and whether it's locked or scanned, and run any `max pdf` action on it
`7`	Files	Pick a folder or a file, see what it holds, and sort, clean, back up or undo with any `max files` action
`8`	AI	Tell the AI agent what you want done; it runs Max's actions, shows each step and asks before it moves, overwrites or deletes files
	Track
`9`	Activity	Three tabs: Queue (running, waiting and finished tasks), History (every action, with filters) and Undo (put back what Max moved, renamed or deleted)
	More
`0`	Extras	Show a QR code for a link, save a screenshot from the clipboard, copy a text file to the clipboard
`,`	Settings	Your defaults (AI, downloads, images, safety) and upkeep: FFmpeg status, data size, cache and undo cleanup

Badges next to a section show what needs a look: a green 2 on Download means two downloads are running. On Activity, a red !1 means one action failed since you last opened Activity; otherwise a yellow 3 means three tasks are waiting or running.

The dashboard remembers whether you left the sidebar open or folded. In a window narrower than 100 columns it always shows icons only.

Each page shows as a neon code: a bar in the page's colour, the key that opens it as two digits, and its name (02 DOWNLOAD). Video is cyan, Audio magenta, Downloads green and so on, the same colours Home's BY TYPE chart uses. The open page's bar and code light up; the others are faded.

For icons, run max config setup-font once: it installs a Nerd Font and offers to make it Windows Terminal's font. The pages then show an icon in their colour before each name (02 󰇚 DOWNLOAD), and the folded sidebar shows the icons. Page icons on the Settings page picks the style:

Auto (the default): icons when Windows Terminal's font is a Nerd Font, neon codes alone otherwise.
Neon codes: never icons.
Nerd Font: always icons. Use it in other terminals once their font is a Nerd Font; without one the icons show as boxes.
Emoji: a colour emoji per page.

Home page¶

Home is the first page you see:

The header greets you with the date and time, and shows your streak once you've used Max two days in a row. Two lights on the right say whether Max found FFmpeg and whether an AI is set up.
Ask Max: type what you want done and press Enter; the AI page opens and runs it. Without an AI set up, Enter opens Settings.
Launchpad: a tile each for Download, Video, Audio, Images, PDF, Files, AI and Activity, with its key and what it's for. Click a tile or press Enter on it. Pick up again lists up to four actions you run most (as many as fit on the row); click one to open its form.
This week, Success %, Space saved, Queue: what you did in the last 7 days next to the 7 days before, how many actions worked, the bytes your compress and optimize runs took off, and the queue right now (click it to open the queue).
Activity and By type: the last 14 days, each day's bar split by kind in the same colours as By type. Under By type, a line counts what worked and what failed. AI counts your requests; what the agent ran counts in its own kind.
Recent: the latest 8 actions: when, whether they worked, what ran on what, what came out (a file, -70%, the error), how long it took, and AI when the agent ran it. Click the card for the full history.
System: CPU (with the last two minutes), memory and disk.

Every number on Home except Queue counts finished actions from the same activity log over the last 14 days, so the cards agree with each other. In a window narrower than 86 columns, the cards stack.

The Activity page's Queue tab reads the same task store as max queue and max grab. See Queue.

Download page¶

Paste a link and press Enter, or wait a moment: the page checks the link. While it checks, the Check button reads "Checking" and the preview shows a spinner with the seconds so far. Then it shows its title, channel, length, chapters, views, likes, upload date, the best video and audio streams, the subtitle languages and the site. Each quality button shows the size you'll get, and the Audio (MP3) buttons show the size at each bitrate.

Part, under the preview, downloads the Whole video (the default) or Only part of it. Pick Only part and type From and To (1:30, 5:00, or 90 seconds); either alone runs from the beginning or to the end. A link with a start time (YouTube's t=1m30s) fills From for you, and To shows the video's length. As you type, the line under the times shows the part, its length and its size at the chosen quality (1:30 to 5:00 · 3:30 of 12:34 · about 109 MB), or what's wrong (an end before the start, a start past the end). Exact cuts starts the part on the second; it's slower. The Download button names the part and its size (⬇ 1:30-5:00 · 109 MB), and the card's corner shows it. A part's row in Transfers carries a PART 1:30-5:00 tag and a clock, since FFmpeg sends no progress for a part. The next link starts from the whole video again.
Options, under Output on the right, holds the other max grab download options: an exact resolution, the YouTube player client, and checkboxes for subtitles and metadata.
Whole playlist, in Options, decides what a link to a video inside a playlist (watch?v=...&list=...) gets. Off (the default while the setting "Single videos drop the playlist part of their link" is on), the page checks and downloads only that video. On, it checks the playlist and lists its items to tick. A playlist link always lists them. Under the list, Select all and Select none tick everything or nothing, and the Items box takes 10 for the first 10, or 5-20 and 1-3,7 for those items; press Enter. The line under it counts the ticked items and their length.
Tags, under Options, shows when the format is Audio (MP3); for video, tick Tags in Options. Tags you hide aren't used. The card sets what goes into the files: artist, album, genre and year (empty fields keep what the site says), whether a playlist's tracks get numbers, whether Artist - Song titles give the artist, and Sort into for Album/ or Artist/Album/ folders. After you check a playlist, the card names the album it will get. The page keeps your Sort into, numbering and title choices for next time.
Transfers has two tabs. Downloads shows one row per download with its progress; "Clear finished" removes the done, failed and cancelled rows. History shows 8 past downloads at a time: type in the filter box to search titles and sites, and use "< Prev" and "Next >" to page. Press Enter on a row, or "Download again", to put its link back in the box. "Copy link" copies it.
Tools sums up your downloads (count, done, failed, total size, sites) and shows whether the YouTube fix is installed. If YouTube downloads fail with HTTP 403, press "Install fix": it does what max grab pot-setup does, after one confirmation. It needs Deno. The other buttons open the download folder, the Activity page's Queue and the settings.

Video page¶

The Video page (3) shows one file in its FILE card. Paste a path or press Browse: the card shows the file's length, picture size, frame rate, codecs, size and bitrate (it needs FFmpeg; without it you see only the size).

Pick an action from its group: Shrink & convert (compress, convert, gif), Cut & join (cut, cut-silence, concat, snap), Sound (to-audio, audio-convert, louder, mute, normalize, denoise) or Picture (brightness, color, stabilize). Its form opens with your file filled in and the same options as the max video command. Every action but concat also takes several files, a folder or a pattern such as *.mp4: see Many files at once. Press Run, or Add to queue to run it later (every action but snap and concat).

Many files at once¶

Some forms on the Video, Audio, PDF and Files pages take more than one file. Their file field says so: "a file, several split by ;, a folder or *.mp4". Type a folder, a pattern such as *.mp4, or several paths split by ;. These forms show one or two checkboxes under the fields:

Subfolders too looks in the subfolders of a folder or pattern as well.
Redo finished files runs files whose result exists already. Without it, a folder or a pattern skips them, and skips Max's own earlier results too. Files you name one by one always run. Actions with no fixed result name (video cut, pdf split, audio clear, files backup) show only Subfolders too.

Leave the output field empty: each result goes next to its file. Run works on several files side by side, and the status line counts them as they finish. When every file has its result already, the status says "Nothing to do". When the action moves, overwrites or deletes files, the question before it starts names how many files it will touch.

Forms for long jobs also have Add to queue: the video actions (but snap and concat), audio compress and denoise, and pdf ocr. It queues one job per file and opens the Jobs window (J). The Activity page's Queue tab lists the jobs too.

Which actions take many files:

Page	Actions
Video	every action but concat
Audio	compress, denoise, transcribe, clear
PDF	split, lock, rip, ocr, form-flatten, optimize
Files	backup

The Images page's actions take a folder on their own; see Images page.

Audio page¶

The Audio page (4) works on one song or a folder of music. Pick a song: the FILE OR FOLDER card shows its length, bitrate, sample rate, size and whether it has cover art, then its title, artist, album, year, track and genre. Pick a folder: it counts the tracks, adds up their length and size, lists their formats, and warns you how many have no title or artist.

The actions sit in three groups: Tags (set, get, batch, clear), Sort (organize) and Sound (compress, denoise, transcribe). set opens with the song's current tags filled in, so you change only what's wrong; a field you've already typed in keeps your text. organize starts with folders by artist and album, and its Dry run box shows the moves before anything happens. Moves can be undone from the Files page (undo). compress, denoise, transcribe and clear also take several songs, a folder or a pattern (see Many files at once), and compress, denoise and transcribe can go to the queue.

Images page¶

The Images page (5) takes one image or a whole folder. Pick an image: the FILE OR FOLDER card shows its size in pixels and megapixels, format, colour mode (colour, greyscale, transparency), frames for an animated GIF, file size, and the date and camera from its EXIF data. It warns you when the image holds a GPS location, which strip removes. Pick a folder: the card shows how many images it holds, their total size and formats, and the folder the results go to (<folder>_optimized). Max reads the images in that folder, not in its subfolders.

The actions sit in two groups: Shrink (compress, resize) and Convert & clean (convert, strip). The picked image or folder fills the action's target.

PDF page¶

The PDF page (6) works like the Video page. Pick a PDF: the FILE card shows its pages, paper size (A4, Letter or millimetres), size, title and author, and how many form fields it has. It tells you when the PDF is locked with a password, and when it has no text on its first pages, which means it's a scan that ocr can read.

The actions sit in five groups: Shrink (compress, optimize), Combine & split (merge, bundle, split, compare), Protect & mark (lock, stamp), Extract (rip, ocr) and Forms (form-data, form-fill, form-flatten). The picked PDF fills the action's first file field; for merge and bundle, press Browse there to add more. split, lock, rip, ocr, form-flatten and optimize also take several PDFs, a folder or a pattern (see Many files at once), and ocr can go to the queue.

Files page¶

The Files page (7) works on a folder or one file. Pick a folder: the FILE OR FOLDER card counts the files directly in it and its subfolders, shows their total size, how many of each kind (images, videos, PDFs ...) and the biggest file. Pick a file: it shows the kind, size and date.

The actions sit in four groups: Organize (order, smart-sort, duplicates), Look (preview, history), Backup & undo (backup, backups, backup-cleanup, undo) and Destroy (shred). Picking a file and then a folder action (order, smart-sort, duplicates) fills in the file's folder. Actions that move or delete files ask first, and undo reverses the last change Max recorded. backup also takes several files, a folder or a pattern (see Many files at once).

Open on another page¶

When you pick a video, an audio file, an image or a PDF on a page that isn't made for it, the card shows a button such as Open on the PDF page (6). It opens that page with the file picked. This works on every page with a FILE card: a PDF picked on the Images page offers the PDF page too.

Browse¶

Every Browse button opens the same window. It starts in the folder of the path already in the field, or where you picked from last time.

Places on the left: Home, Desktop, Documents, Downloads, Pictures, Videos and Music (the ones you have), Max downloads (the folder the Download page saves into), your pinned folders, folders you picked from lately, and the drives.
The path bar: < goes back, ^ goes up a folder. Type or paste a path and press Enter to go there; a file path picks that file.
The list: folders first, then files with their size and date. Type in the filter box (Ctrl+F) to narrow it. Enter opens a folder or picks a file, Backspace goes up and puts you back on the folder you left, Alt+Left goes back.
On the Video, Images and PDF pages the list shows only the files that page works on. Tick All files to see everything, and Hidden files to see hidden ones.
Pin this folder adds the open folder to Places for next time.

Fields that take a folder pick the open one. They list the page's files too, dimmed, so you can see which folder holds your songs or photos; the line under the list counts them. Fields for a file Max writes (an output) ask for a file name and save it in the open folder. Fields that take a file also have Use this folder, for actions that work on a whole folder.

Activity page¶

The Activity page (9) has three tabs. Queue opens first; the Download page's Queue button opens it too.

Queue¶

The Queue tab shows the work the dashboard runs, one task at a time. At the top, four counters show what's running and waiting, and how many tasks finished or failed today. The light in the corner says whether the queue is running.

Now running shows the running task with its progress, speed and time left. Cancel stops it.
Up next lists the waiting tasks in the order they'll run. Each one has Pause (or Resume) and Cancel. "Pause all", "Resume all" and "Clear waiting" act on the whole list; "Clear waiting" asks first and leaves the running task alone.
Finished shows the last 8 tasks. Retry puts a failed or cancelled task back in line, "Run again" repeats a finished one, and "Open folder" opens where its files went. "All activity (History)" opens the History tab.

History¶

Every action you ran from the dashboard, newest first, 10 at a time with Prev and Next. Pick a kind (Video, Audio, PDF, Downloads ...), tick Failed only, or search by name, file or message. The line under the list shows the highlighted action in full: its message or error, its output files and the options it ran with. Clear history asks first and leaves your files alone.

Undo¶

The file changes Max recorded (organize, order, smart-sort and duplicates --delete), newest first, with the folder each one changed. Undo puts back the newest change that isn't undone yet, after one confirmation; press it again to step further back. Folders that a change created, such as organize's Artist/Album folders, go too when they're empty again.

AI page¶

The AI page (8) runs the same agent as max ai ask. Type what you want done, such as "shrink every video in this folder", or press one of the examples. The conversation scrolls on its own, so the input below it stays in view; up and down in the input bring back earlier requests.

Each answer starts with a status line: a spinner and what Max is doing ("Thinking", "Running files order", "Waiting for your answer"), then how many actions it ran and the tokens it used.
Every action gets a card: running, then ✓ with its result and how long it took, ✗ with the error, or a note when a path was refused, you said no, or it was a dry run. Click a card to see the arguments it ran with and the files it made.
Long jobs (compressing or cleaning up a video, downloads) can go to the queue: the card says ⧗ queued, you keep talking, and the Jobs window (J) shows their progress. In a terminal, max "<request>" can queue long jobs too: a background worker runs them, and max queue status shows them.
The line under the status names what it looked at first: folders it listed or searched, files it inspected, links it checked.
The reply itself is rendered as Markdown: lists, tables, code and links.
Before an action moves, overwrites or deletes files, a dialog shows the exact action and asks you.
Open folder opens where the results went, and Undo... opens Activity's Undo tab when files changed.
Dry run shows the steps and changes nothing. New chat starts over. The line beside them shows the model and the tokens the chat used.
Stop takes the place of Send while a request runs. It stops the agent after its current step (a download stops at once); the answer says how many actions finished.
Notes shows what the agent remembers between chats. Add a note in the box and press Enter, or delete one; the next request uses the change.
When a job you queued (from this page, another page or the CLI) finishes or fails, a notice says so, wherever you are in the dashboard.
When neither the main AI nor the fallback is set up (each needs a model, and an API key unless it's Ollama), the page says so and links to Settings.

Each request and each action the agent runs shows on Activity's History tab.

Extras page¶

The Extras page (0) holds the max tools actions, one card each:

Share as QR code: type a link or any text and press Run. The code appears on the page; point your phone's camera at it. Use it to open a local dev server on your phone.
Save clipboard image: saves the image on your clipboard, such as a screenshot. The file name starts as a new dated name in your Pictures folder (clipboard-20261002-153012.png), so pastes never replace each other. Tick Overwrite to replace a file that has the name you typed. After a save, "Open on the Images page" opens the picture there.
Copy text file: puts a text file's contents on the clipboard.

Find any action (Ctrl+P)¶

Press Ctrl+P and type part of an action's or a page's name, such as merge or pdf compress. Each result shows the page it's on and what it does. Press Enter to open that page with the action's form shown and the cursor in its first field. With nothing typed, the list shows every page and action. Theme commands are there too.

Settings page¶

The Settings page (,) edits the same settings as max config, saved in ~/.max_config.env. It shows only settings that change something:

AI: two slots, Main AI and Fallback. In each, pick a provider (OpenAI or compatible, OpenRouter, Google Gemini, Ollama, or no fallback), and the slot shows only what that provider needs:
its API key (hidden; press Show), with where to get one; Ollama needs none;
a URL for an OpenAI-compatible service, or where Ollama runs;
the model: type any name (suggestions from the provider's list complete as you type), or press Browse... for the provider's list, searchable: type part of a name ("flash", "5 mini"), move with the arrows, Enter picks. A name the list doesn't show can be typed and picked too. Until the list loads, a few known models are offered; for Gemini the -latest names (gemini-flash-latest, gemini-pro-latest) follow Google's newest release. OpenRouter and Gemini start with no model.
the image model for max ai create and edit, picked the same way from the provider's image models (Gemini's Nano Banana gemini-3.1-flash-image, for example). Leave it empty and that provider makes no images. Ollama has none.
Test sends one tiny request with what's on screen, before you save, and says "✓ Works" or what's wrong ("no credit left (402)", "quota or rate limit reached (429)", "the API key is wrong (401)").

The fallback can't be the same provider as the main AI. Each provider keeps its own key: switching a slot to another provider and back keeps what you typed, and Save writes only the chosen providers' settings. If your OpenAI key was set up with OpenRouter's URL, switching to OpenRouter fills that key in. Images follow the same main AI and fallback: max ai create uses the main AI's image model, and the fallback's when the main one fails. - Downloads: the folder, format, quality, how many downloads run at once, metadata, and playlist links. - Images: the default quality and how many images run at once. - Dashboard: Page icons: auto, neon codes, Nerd Font or emoji (see Sections). - Safety and network: whether Max asks before it moves, overwrites or deletes files, how many more times the queue runs a task that failed, and how long a download waits for data.

"Save changes" checks the values first, writes only the settings you changed and applies them at once; "Downloads at once" and "Page icons" apply the next time max starts. "Discard" drops your edits and shows the saved values again. An empty API key removes it from the file. If a .env file in the folder you started max from sets the same settings, it wins; Maintenance says so.

Maintenance shows the Max, Python and system versions, whether FFmpeg is found, and how much ~/.max_cli holds (Open folder opens it). Its other buttons clear the cache, remove undo backups and undo records older than 30 days, and reset every setting by removing ~/.max_config.env. Each one asks first. If your settings file still sets something Max no longer has, such as VERBOSE, Maintenance names it and Remove them deletes those lines. The dashboard points them out when it starts, too.

Jobs window¶

Press J to open or close the Jobs window above the footer. It shows the task running now, with its progress, speed and time left, then the tasks waiting their turn, then the last few that finished, failed or were cancelled. It opens by itself when you press "Queue for later" on the Download page or "Add to queue" on an action's form.

While the dashboard is open it runs queued tasks one after another, including any left from earlier runs. To cancel or retry a task, open Activity (9).

Theme¶

The dashboard uses its own dark theme, max-cyber. Press Ctrl+P and search "theme" to try another one; the dashboard remembers your choice.

Keyboard Shortcuts¶

Key	Action
`1` to `9`, `0`	Jump to a section
`,`	Settings
`Alt+Left`	Back to the previous section
`Esc`	Move to the sidebar
`?`	Show every shortcut
`J`	Show or hide the Jobs window
`Ctrl+P`	Find any action or page by name; themes
`q`	Quit
`r`	Refresh the pages
`Ctrl+B`	Collapse or expand the sidebar
`Tab` / `Shift+Tab`	Move between buttons and fields
`Enter`	Press the focused button

Number keys and q type into a text field when one has focus. Press Esc first to leave the field.

Troubleshooting¶

"The dashboard needs the 'textual' library, which is missing"¶

Your install is broken or partly removed. Reinstall Max:

pip install --upgrade max-cli

`max` prints help instead of opening the dashboard¶

max opens the dashboard only when both its input and its output are a terminal. Run it directly, without | or >, or run max dashboard.

Dashboard not refreshing¶

Press r to refresh. The visible section also refreshes every 2 seconds.