feat: allow starting a session with an initial command (#5543)

* feat: allow starting a session with an initial command

* add pr

Author: imsnif

CHANGELOG.md

@@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 * fix: properly fire visibility event to plugins when their tab/floating-layer is hidden/shown (https://github.com/zellij-org/zellij/pull/5518 and https://github.com/zellij-org/zellij/pull/5534)
 * feat: allow setting explicit_theme_hue (light/dark) (https://github.com/zellij-org/zellij/pull/5536)
 * fix: input mode updates when switching tabs (https://github.com/zellij-org/zellij/pull/5535)
+* feat: allow starting a session with an initial command, eg. `zellij attach -a my-session -- htop` (https://github.com/zellij-org/zellij/pull/5543)
 
 ## [0.45.0] - 2026-08-20
 * feat: allow tabs to have different sizes if clients aren't focused on the same one (https://github.com/zellij-org/zellij/pull/5133)

src/commands.rs

@@ -37,7 +37,7 @@ use zellij_utils::{
     data::ConnectToSession,
     envs,
     input::{
-        actions::Action,
+        actions::{initial_panes_from_cli, Action},
         config::{Config, ConfigError},
         options::Options,
     },
@@ -229,7 +229,7 @@ pub(crate) fn start_web_server(
 }
 
 fn create_new_client() -> ClientInfo {
-    ClientInfo::New(generate_unique_session_name_or_exit(), None, None)
+    ClientInfo::New(generate_unique_session_name_or_exit(), None, None, None)
 }
 
 #[cfg(feature = "web_server_capability")]
@@ -559,7 +559,7 @@ fn attach_with_session_name(
     match &session_name {
         Some(session) if create => match session_exists(session) {
             Ok(true) => ClientInfo::Attach(session_name.unwrap(), config_options),
-            Ok(false) => ClientInfo::New(session_name.unwrap(), None, None),
+            Ok(false) => ClientInfo::New(session_name.unwrap(), None, None, None),
             Err(kind) => {
                 eprintln!("{}", session_listing_error_message(kind));
                 process::exit(1);
@@ -665,6 +665,9 @@ pub(crate) fn start_client(opts: CliArgs) {
                     forget: false,
                     ca_cert: None,
                     insecure: false,
+                    initial_command: vec![],
+                    close_on_exit: false,
+                    start_suspended: false,
                 }));
             } else {
                 opts.command = None;
@@ -700,6 +703,9 @@ pub(crate) fn start_client(opts: CliArgs) {
             forget,
             ca_cert,
             insecure,
+            initial_command,
+            close_on_exit,
+            start_suspended,
         })) = opts.command.clone()
         {
             if let Some(remote_session_url) = session_name.as_ref().and_then(|s| {
@@ -719,6 +725,11 @@ pub(crate) fn start_client(opts: CliArgs) {
                     std::process::exit(2);
                 }
 
+                if !initial_command.is_empty() {
+                    eprintln!("Cannot run an initial command on a remote session.");
+                    std::process::exit(2);
+                }
+
                 #[cfg(feature = "web_server_capability")]
                 if let Err(e) = zellij_client::start_remote_client(
                     Box::new(os_input.clone()),
@@ -803,6 +814,18 @@ pub(crate) fn start_client(opts: CliArgs) {
                     client.set_cwd(new_session_cwd);
                 }
 
+                let current_dir = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+                if let Some(initial_panes) = initial_panes_from_cli(
+                    initial_command,
+                    None,
+                    Some(current_dir.clone()),
+                    current_dir,
+                    close_on_exit,
+                    start_suspended,
+                ) {
+                    client.set_initial_panes(initial_panes);
+                }
+
                 let tab_position_to_focus = reconnect_to_session
                     .as_ref()
                     .and_then(|r| r.tab_position.clone());
@@ -829,7 +852,7 @@ pub(crate) fn start_client(opts: CliArgs) {
                     opts,
                     config,
                     config_options,
-                    ClientInfo::New(session_name, layout_info, new_session_cwd),
+                    ClientInfo::New(session_name, layout_info, new_session_cwd, None),
                     None,
                     None,
                     is_a_reconnect,
@@ -876,7 +899,12 @@ pub(crate) fn start_client(opts: CliArgs) {
                                 opts,
                                 config,
                                 config_options.clone(),
-                                ClientInfo::New(session_name.clone(), layout_info, new_session_cwd),
+                                ClientInfo::New(
+                                    session_name.clone(),
+                                    layout_info,
+                                    new_session_cwd,
+                                    None,
+                                ),
                                 None,
                                 None,
                                 is_a_reconnect,
@@ -899,7 +927,7 @@ pub(crate) fn start_client(opts: CliArgs) {
                     opts,
                     config,
                     config_options,
-                    ClientInfo::New(session_name, layout_info, new_session_cwd),
+                    ClientInfo::New(session_name, layout_info, new_session_cwd, None),
                     None,
                     None,
                     is_a_reconnect,

zellij-client/src/lib.rs

@@ -157,7 +157,9 @@ use zellij_utils::cli::CliArgs;
 use zellij_utils::{
     channels::{self, ChannelWithContext, SenderWithContext},
     consts::{set_permissions, ZELLIJ_SOCK_DIR},
-    data::{ClientId, ConnectToSession, KeyWithModifier, LayoutInfo, LayoutMetadata},
+    data::{
+        ClientId, CommandOrPlugin, ConnectToSession, KeyWithModifier, LayoutInfo, LayoutMetadata,
+    },
     envs,
     errors::{ClientContext, ContextType, ErrorInstruction},
     input::{
@@ -503,7 +505,12 @@ pub fn spawn_server(socket_path: &Path, debug: bool) -> io::Result<()> {
 #[derive(Debug, Clone)]
 pub enum ClientInfo {
     Attach(String, Options),
-    New(String, Option<LayoutInfo>, Option<PathBuf>), // PathBuf -> explicit cwd
+    New(
+        String,
+        Option<LayoutInfo>,
+        Option<PathBuf>,
+        Option<Vec<CommandOrPlugin>>,
+    ), // PathBuf -> explicit cwd
     Resurrect(String, PathBuf, bool, Option<PathBuf>), // (name, path_to_layout, force_run_commands, cwd)
     Watch(String, Options),                            // Watch mode (read-only)
 }
@@ -512,24 +519,30 @@ impl ClientInfo {
     pub fn get_session_name(&self) -> &str {
         match self {
             Self::Attach(ref name, _) => name,
-            Self::New(ref name, _layout_info, _layout_cwd) => name,
+            Self::New(ref name, _layout_info, _layout_cwd, _initial_panes) => name,
             Self::Resurrect(ref name, _, _, _) => name,
             Self::Watch(ref name, _) => name,
         }
     }
     pub fn set_layout_info(&mut self, new_layout_info: LayoutInfo) {
         match self {
-            ClientInfo::New(_, layout_info, _) => *layout_info = Some(new_layout_info),
+            ClientInfo::New(_, layout_info, _, _) => *layout_info = Some(new_layout_info),
             _ => {},
         }
     }
     pub fn set_cwd(&mut self, new_cwd: PathBuf) {
         match self {
-            ClientInfo::New(_, _, cwd) => *cwd = Some(new_cwd),
+            ClientInfo::New(_, _, cwd, _) => *cwd = Some(new_cwd),
             ClientInfo::Resurrect(_, _, _, cwd) => *cwd = Some(new_cwd),
             _ => {},
         }
     }
+    pub fn set_initial_panes(&mut self, new_initial_panes: Vec<CommandOrPlugin>) {
+        match self {
+            ClientInfo::New(_, _, _, initial_panes) => *initial_panes = Some(new_initial_panes),
+            _ => {},
+        }
+    }
 }
 
 #[derive(Debug, Clone)]
@@ -1031,6 +1044,7 @@ pub fn start_client(
                 force_run_layout_commands: false,
                 cwd: None,
                 host_terminal_env: host_terminal_env(),
+                initial_panes: None,
             };
             (
                 ClientToServerMsg::AttachClient {
@@ -1077,6 +1091,7 @@ pub fn start_client(
                 force_run_layout_commands: force_run_commands,
                 cwd,
                 host_terminal_env: host_terminal_env(),
+                initial_panes: None,
             };
 
             os_input.update_session_name(name);
@@ -1101,7 +1116,7 @@ pub fn start_client(
                 ipc_pipe,
             )
         },
-        ClientInfo::New(name, layout_info, layout_cwd) => {
+        ClientInfo::New(name, layout_info, layout_cwd, initial_panes) => {
             envs::set_session_name(name.clone());
 
             let cli_assets = CliAssets {
@@ -1134,6 +1149,7 @@ pub fn start_client(
                 force_run_layout_commands: false,
                 cwd: layout_cwd,
                 host_terminal_env: host_terminal_env(),
+                initial_panes,
             };
 
             os_input.update_session_name(name);
@@ -1652,6 +1668,7 @@ pub fn start_server_detached(
                 force_run_layout_commands: force_run_commands,
                 cwd,
                 host_terminal_env: host_terminal_env(),
+                initial_panes: None,
             };
 
             os_input.update_session_name(name);
@@ -1676,7 +1693,7 @@ pub fn start_server_detached(
                 ipc_pipe,
             )
         },
-        ClientInfo::New(name, layout_info, layout_cwd) => {
+        ClientInfo::New(name, layout_info, layout_cwd, initial_panes) => {
             envs::set_session_name(name.clone());
 
             let cli_assets = CliAssets {
@@ -1710,6 +1727,7 @@ pub fn start_server_detached(
                 force_run_layout_commands: false,
                 cwd: layout_cwd,
                 host_terminal_env: host_terminal_env(),
+                initial_panes,
             };
 
             os_input.update_session_name(name);

zellij-client/src/web_client/session_management.rs

@@ -103,6 +103,7 @@ pub fn create_first_message(
             force_run_layout_commands: false,
             cwd: None,
             host_terminal_env: Default::default(),
+            initial_panes: None,
         };
 
         ClientToServerMsg::FirstClientConnected {
@@ -123,6 +124,7 @@ pub fn create_first_message(
             force_run_layout_commands: false,
             cwd: None,
             host_terminal_env: Default::default(),
+            initial_panes: None,
         };
         let is_web_client = true;
 

zellij-integration-tests/src/lib.rs

@@ -23,7 +23,10 @@ pub use nested::{
     host_descended_bar_with_ascend_keys_settled, wait_for_settled_composite,
     NestedDepthThreeHarness, NestedHarness,
 };
-pub use runner::{assert_same_rendered_grid, normalized, TestClient, TestRunner, TestSession};
+pub use runner::{
+    assert_same_rendered_grid, normalized, BackgroundTestSession, TestClient, TestRunner,
+    TestSession,
+};
 pub use zellij_utils::data::LayoutInfo;
 pub use zellij_utils::pane_size::Size;