ctl: interactive shell with history, editing and completion

`rsp ctl` opens a prompt in the spirit of bluetoothctl. Lines are parsed with
the same clap definitions as the one-shot CLI, so every command and flag works
exactly as it does from a terminal, `help <command>` included.

Tab completes subcommands, and track/album/artist paths for `play` through
`db-complete` (run out of process, keeping its 100 ms timeout away from the
input loop). History lives in the state directory. Piped input falls back to a
plain line loop, so `rsp ctl < commands` works without a terminal.

7 files changed, 450 insertions, 0 deletions

diff --git a/Cargo.lock b/Cargo.lock
index 7a4524a..13f394e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -19,6 +19,7 @@ dependencies = [
  "rand 0.10.1",
  "reqwest",
  "rusqlite",
+ "rustyline",
  "serde",
  "serde_json",
  "symphonia",
@@ -422,6 +423,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
 
 [[package]]
+name = "clipboard-win"
+version = "5.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "052af7878466feccda12ba7a6a67d019d712f296809559b47c12c8cc196d3a9a"
+dependencies = [
+ "error-code",
+]
+
+[[package]]
 name = "cmake"
 version = "0.1.58"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -667,6 +677,12 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099"
 
 [[package]]
+name = "endian-type"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "869b0adbda23651a9c5c0c3d270aac9fcb52e8622a8f2b17e57802d7791962f2"
+
+[[package]]
 name = "enumflags2"
 version = "0.7.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -704,6 +720,12 @@ dependencies = [
 ]
 
 [[package]]
+name = "error-code"
+version = "3.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b5343afd4a8365a643ac588dab4cf234a190c7f6c88c9f6dd6ffe00837661b7"
+
+[[package]]
 name = "event-listener"
 version = "5.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -961,6 +983,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
 
 [[package]]
+name = "home"
+version = "0.5.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc627f471c528ff0c4a49e1d5e60450c8f6461dd6d10ba9dcd3a61d3dff7728d"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
 name = "http"
 version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -1459,6 +1490,15 @@ dependencies = [
 ]
 
 [[package]]
+name = "nibble_vec"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77a5d83df9f36fe23f0c3648c6bbb8b0298bb5f1939c8f2704431371f4b84d43"
+dependencies = [
+ "smallvec",
+]
+
+[[package]]
 name = "nix"
 version = "0.31.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -1861,6 +1901,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
 [[package]]
+name = "radix_trie"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b4431027dcd37fc2a73ef740b5f233aa805897935b8bce0195e41bbf9a3289a"
+dependencies = [
+ "endian-type",
+ "nibble_vec",
+]
+
+[[package]]
 name = "rand"
 version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -2115,6 +2165,26 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
 [[package]]
+name = "rustyline"
+version = "19.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56e1d6bd81c2d5feafd2419138df9183c45a10a492c4e873b8b0acb8eb2b549e"
+dependencies = [
+ "bitflags",
+ "clipboard-win",
+ "home",
+ "libc",
+ "log",
+ "memchr",
+ "nix",
+ "radix_trie",
+ "unicode-segmentation",
+ "unicode-width",
+ "utf8parse",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
 name = "ryu"
 version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -2843,6 +2913,18 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
 [[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca718471876992059f251e33aafc334346ada08042b7661dd1fe313a9bced557"
+
+[[package]]
 name = "unicode-xid"
 version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
diff --git a/Cargo.toml b/Cargo.toml
index 51eebbb..ee4a077 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -36,6 +36,7 @@ notify-rust = "4.17.0"
 md-5 = "0.11.0"
 hex = "0.4.3"
 zbus = { version = "5", default-features = false, features = ["blocking-api"] }
+rustyline = "19.0.0"
 
 [profile.release]
 opt-level = "z"
diff --git a/README.md b/README.md
index 678d085..f8d4ff5 100644
--- a/README.md
+++ b/README.md
@@ -69,4 +69,5 @@ these are normal commands:
 - `status`        Show player status
 - `scan`          Scan music paths to populate database
 - `settings`      Settings management
+- `ctl`           Interactive shell with history and tab completion (like bluetoothctl)
 - `help`          Print this message or the help of the given subcommand(s)
diff --git a/src/cli.rs b/src/cli.rs
index 79c31a8..8b39519 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -104,6 +104,8 @@ pub enum Commands {
     },
     /// display lyrics
     Lyrics,
+    /// Interactive control shell (like bluetoothctl)
+    Ctl,
 }
 
 #[derive(Subcommand)]
@@ -350,6 +352,9 @@ impl Cli {
             Commands::Lyrics => {
                 let _ = crate::daemon::send_command("lyrics".to_string());
             }
+            Commands::Ctl => {
+                crate::ctl::run()?;
+            }
         }
         Ok(())
     }
diff --git a/src/ctl.rs b/src/ctl.rs
new file mode 100644
index 0000000..5cb2f3b
--- /dev/null
+++ b/src/ctl.rs
@@ -0,0 +1,359 @@
+/*
+ * This file is a part of RSPlayer
+ * Licensed under the GPL-3.0 License
+ * Copyright (C) 2026 Salmonik @ salmonik@tuta.io
+ * https://codeberg.org/salmonik/RSPlayer
+*/
+
+//! Interactive control shell (`rsp ctl`), in the spirit of `bluetoothctl`.
+//!
+//! Every line is parsed with the same clap definitions as the one-shot CLI, so
+//! the shell understands exactly the same commands (`play --now …`,
+//! `volume +5`, `settings set …`) instead of keeping a second, drifting copy.
+//! History is kept in the state directory, and Tab completes commands plus
+//! track/album paths for `play`.
+
+use crate::cli::Cli;
+use clap::{CommandFactory, Parser};
+use rustyline::completion::{Completer, Pair};
+use rustyline::error::ReadlineError;
+use rustyline::highlight::Highlighter;
+use rustyline::hint::Hinter;
+use rustyline::history::DefaultHistory;
+use rustyline::validate::Validator;
+use rustyline::{Context, Editor, Helper};
+use std::io::IsTerminal;
+use std::process::{Command, Stdio};
+
+const PROMPT: &str = "rsp> ";
+
+/// Commands the shell handles itself.
+const LOCAL_COMMANDS: [&str; 5] = ["help", "quit", "exit", "clear", "?"];
+
+struct CtlHelper {
+    commands: Vec<String>,
+}
+
+impl Default for CtlHelper {
+    fn default() -> Self {
+        let mut commands: Vec<String> = Cli::command()
+            .get_subcommands()
+            .map(|command| command.get_name().to_string())
+            .chain(LOCAL_COMMANDS.iter().map(|c| c.to_string()))
+            .collect();
+        commands.sort();
+        commands.dedup();
+        Self { commands }
+    }
+}
+
+impl Helper for CtlHelper {}
+impl Highlighter for CtlHelper {}
+impl Hinter for CtlHelper {
+    type Hint = String;
+}
+impl Validator for CtlHelper {}
+
+impl Completer for CtlHelper {
+    type Candidate = Pair;
+
+    fn complete(
+        &self,
+        line: &str,
+        pos: usize,
+        _ctx: &Context<'_>,
+    ) -> rustyline::Result<(usize, Vec<Pair>)> {
+        let before = &line[..pos];
+        let Some(start) = before.rfind(char::is_whitespace).map(|i| i + 1) else {
+            let prefix = before.to_string();
+            let matches = self
+                .commands
+                .iter()
+                .filter(|command| command.starts_with(&prefix))
+                .map(|command| Pair {
+                    display: command.clone(),
+                    replacement: command.clone(),
+                })
+                .collect();
+            return Ok((0, matches));
+        };
+
+        let word = &before[start..];
+        let command = before[..start].trim();
+        let matches = match command {
+            "play" | "play-album" => complete_music(word),
+            _ => Vec::new(),
+        };
+        Ok((start, matches))
+    }
+}
+
+/// Candidate tracks/albums for the current prefix, from `rsp db-complete`.
+///
+/// Completion runs out of process on purpose: `db-complete` already applies the
+/// 100 ms database timeout and the filesystem fallback, so a slow or missing
+/// index cannot hang the shell's input loop.
+fn complete_music(prefix: &str) -> Vec<Pair> {
+    let Ok(exe) = std::env::current_exe() else {
+        return Vec::new();
+    };
+    let Ok(output) = Command::new(exe)
+        .arg("db-complete")
+        .arg(prefix)
+        .stderr(Stdio::null())
+        .output()
+    else {
+        return Vec::new();
+    };
+
+    String::from_utf8_lossy(&output.stdout)
+        .lines()
+        .map(str::trim)
+        .filter(|candidate| !candidate.is_empty())
+        // The CLI escapes spaces for shells; the shell's own reader needs the
+        // real text back and re-quotes it below.
+        .map(unescape)
+        .map(|candidate| Pair {
+            display: candidate.clone(),
+            replacement: quote(&candidate),
+        })
+        .collect()
+}
+
+/// Undo the shell escaping `rsp db-complete` applies.
+fn unescape(candidate: &str) -> String {
+    let mut out = String::with_capacity(candidate.len());
+    let mut chars = candidate.chars();
+    while let Some(c) = chars.next() {
+        if c == '\\' {
+            if let Some(next) = chars.next() {
+                out.push(next);
+            }
+        } else {
+            out.push(c);
+        }
+    }
+    out
+}
+
+/// Quote a candidate that contains spaces, so it stays one argument.
+fn quote(candidate: &str) -> String {
+    if candidate.contains(char::is_whitespace) {
+        format!("'{}'", candidate.replace('\'', r"'\''"))
+    } else {
+        candidate.to_string()
+    }
+}
+
+/// Split a command line into arguments, honouring quotes and backslash
+/// escapes so that track names with spaces survive.
+fn split_args(line: &str) -> Vec<String> {
+    let mut args = Vec::new();
+    let mut current = String::new();
+    let mut quote: Option<char> = None;
+    let mut in_word = false;
+    let mut chars = line.chars();
+
+    while let Some(c) = chars.next() {
+        match quote {
+            Some(q) => {
+                if c == q {
+                    quote = None;
+                } else if c == '\\' && q == '"' {
+                    current.extend(chars.next());
+                } else {
+                    current.push(c);
+                }
+            }
+            None => match c {
+                '\'' | '"' => {
+                    quote = Some(c);
+                    in_word = true;
+                }
+                '\\' => {
+                    current.extend(chars.next());
+                    in_word = true;
+                }
+                c if c.is_whitespace() => {
+                    if in_word {
+                        args.push(std::mem::take(&mut current));
+                        in_word = false;
+                    }
+                }
+                c => {
+                    current.push(c);
+                    in_word = true;
+                }
+            },
+        }
+    }
+    if in_word {
+        args.push(current);
+    }
+    args
+}
+
+enum Step {
+    Continue,
+    Quit,
+}
+
+fn dispatch(line: &str) -> Result<Step, Box<dyn std::error::Error>> {
+    let mut args = split_args(line);
+    let Some(command) = args.first().cloned() else {
+        return Ok(Step::Continue);
+    };
+
+    match command.as_str() {
+        "quit" | "exit" | "q" => return Ok(Step::Quit),
+        "clear" => {
+            print!("\x1b[2J\x1b[H");
+            return Ok(Step::Continue);
+        }
+        "help" | "?" => {
+            let mut cli = Cli::command();
+            match args.get(1).and_then(|name| cli.find_subcommand_mut(name)) {
+                Some(subcommand) => {
+                    subcommand.print_help()?;
+                    println!();
+                }
+                None => {
+                    cli.print_help()?;
+                    println!();
+                }
+            }
+            return Ok(Step::Continue);
+        }
+        // These replace or block the process the shell runs in.
+        "start-daemon" | "ctl" => {
+            return Err(format!(
+                "`{}` would take over the shell — run it from a normal terminal",
+                command
+            )
+            .into());
+        }
+        _ => {}
+    }
+
+    args.insert(0, "rsp".to_string());
+    match Cli::try_parse_from(args) {
+        Ok(cli) => cli.run()?,
+        Err(e)
+            if matches!(
+                e.kind(),
+                clap::error::ErrorKind::DisplayHelp | clap::error::ErrorKind::DisplayVersion
+            ) =>
+        {
+            print!("{}", e);
+        }
+        Err(e) => eprintln!("{}", e.render()),
+    }
+    Ok(Step::Continue)
+}
+
+pub fn run() -> Result<(), Box<dyn std::error::Error>> {
+    if !std::io::stdin().is_terminal() {
+        return run_piped();
+    }
+
+    let history_path = crate::config::runtime_dir().join("ctl_history");
+    let mut editor: Editor<CtlHelper, DefaultHistory> = Editor::default()?;
+    let _ = editor.load_history(&history_path);
+
+    if !crate::config::Config::get_socket_path().exists() {
+        eprintln!("note: no daemon socket — start it with `start-daemon` or the service");
+    }
+    println!("RSPlayer control shell — `help` lists commands, `quit` leaves.");
+    loop {
+        match editor.readline(PROMPT) {
+            Ok(line) => {
+                let line = line.trim().to_string();
+                if line.is_empty() {
+                    continue;
+                }
+                let _ = editor.add_history_entry(line.as_str());
+                match dispatch(&line) {
+                    Ok(Step::Continue) => {}
+                    Ok(Step::Quit) => break,
+                    Err(e) => eprintln!("Error: {}", e),
+                }
+            }
+            // Ctrl-C drops the line, Ctrl-D leaves.
+            Err(ReadlineError::Interrupted) => continue,
+            Err(ReadlineError::Eof) => break,
+            Err(e) => {
+                eprintln!("Input error: {}", e);
+                break;
+            }
+        }
+    }
+
+    let _ = editor.save_history(&history_path);
+    Ok(())
+}
+
+/// Same commands without an editor, for pipes and scripts
+/// (`rsp ctl < commands.txt`), where rustyline has no terminal to drive.
+fn run_piped() -> Result<(), Box<dyn std::error::Error>> {
+    use std::io::BufRead;
+
+    for line in std::io::stdin().lock().lines() {
+        match dispatch(line?.trim()) {
+            Ok(Step::Continue) => {}
+            Ok(Step::Quit) => break,
+            Err(e) => eprintln!("Error: {}", e),
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::Parser;
+
+    #[test]
+    fn splits_plain_and_quoted_arguments() {
+        assert_eq!(split_args("seek 1:30"), vec!["seek", "1:30"]);
+        assert_eq!(
+            split_args("play 'Some Album/01 Track.mp3'"),
+            vec!["play", "Some Album/01 Track.mp3"]
+        );
+        assert_eq!(
+            split_args(r#"play "A \"quoted\" name""#),
+            vec!["play", r#"A "quoted" name"#]
+        );
+        assert_eq!(split_args("  status  "), vec!["status"]);
+        assert!(split_args("   ").is_empty());
+    }
+
+    #[test]
+    fn quoted_arguments_round_trip_through_the_cli() {
+        let args = split_args("seek +15");
+        let mut full = vec!["rsp".to_string()];
+        full.extend(args);
+        let cli = Cli::try_parse_from(full).expect("seek +15 is a valid command");
+        assert!(matches!(cli.command, crate::cli::Commands::Seek { .. }));
+    }
+
+    #[test]
+    fn quotes_single_word_arguments_only_when_needed() {
+        assert_eq!(quote("AFX"), "AFX");
+        assert_eq!(
+            quote("Analogue Bubblebath, Vol 3.1"),
+            "'Analogue Bubblebath, Vol 3.1'"
+        );
+    }
+
+    #[test]
+    fn completes_command_names() {
+        let helper = CtlHelper::default();
+        for expected in ["play", "seek", "settings", "status", "quit"] {
+            assert!(
+                helper.commands.iter().any(|c| c == expected),
+                "completion is missing `{}`",
+                expected
+            );
+        }
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index 189c376..fe0a3b6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -15,6 +15,7 @@ pub fn debug_eprintln(args: core::fmt::Arguments<'_>) {
 pub mod audio;
 pub mod cli;
 pub mod config;
+pub mod ctl;
 pub mod daemon;
 pub mod database;
 pub mod mpris;
diff --git a/src/main.rs b/src/main.rs
index 4bc4498..0138ea2 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -8,6 +8,7 @@
 mod audio;
 mod cli;
 mod config;
+mod ctl;
 mod daemon;
 mod database;
 mod mpris;