Swift API

method libtmux-swift latest

Server.newSession(named:startDirectory:windowName:width:height:environment:shell:)

Creates a detached session.

Source and package

Qualified name: Server.newSession(named:startDirectory:windowName:width:height:environment:shell:)
Declared in: Server
Package: libtmux-swift
Source: Sources/LibTmux/Creation.swift
Other languages: Perlmethod Erlang PowerShell Julia Elixir Haskell Common Lisp PythonRubyLuaTypeScriptRustGoJavaC#C++KotlinScalaOCaml F# Clojure

newSession( named: String, startDirectory: String?, windowName: String?, width: Int?, height: Int?, environment: [String: String], shell: String? ) -> Session method async [source] ¶

Description#

Environment entries are available to the first pane as it starts. shell, given, replaces the pane's default shell as the command tmux spawns — the same trailing argument new-session itself accepts.

Examples#

Create a session and refresh its snapshot. Create a detached session with an editor window, add a logs window, then look up the session by its stable ID. The original Session still reports one window; the fresh snapshot reports two. Use Swift 6.2 or newer and tmux 3.3a or newer on Linux or macOS. In an empty directory, save this consumer package as Package.swift; SwiftPM fetches the library from release 0.1.1:

// swift-tools-version: 6.2
import PackageDescription

let package = Package(
    name: "ApiExample",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(url: "https://github.com/libtmux/libtmux-swift.git", from: "0.1.1")
    ],
    targets: [
        .executableTarget(
            name: "ApiExample",
            dependencies: [
                .product(name: "LibTmux", package: "libtmux-swift"),
                .product(name: "TmuxFixture", package: "libtmux-swift"),
            ],
            path: "Sources"
        )
    ]
)

Create a Sources directory and save this complete program as Sources/Example.swift. The withTmuxServer fixture owns a private tmux server and stops it after success or failure. Ordinary application code uses Server for its own socket; these examples use the fixture until their setup moves to ordinary server objects. View source

import Foundation
import LibTmux
import TmuxFixture

@main
struct ApiNewSession {
    static func main() async {
        do {
            try await withTmuxServer { @Sendable server in
                let session = try await server.newSession(named: "work", windowName: "editor")
                _ = try await server.newWindow(in: session, named: "logs")
                guard let refreshed = try await server.session(session.id) else {
                    throw ExampleError.sessionDisappeared
                }
                print("Created: \(session.name)")
                print("Original windows: \(session.windowCount)")
                print("Current windows: \(refreshed.windowCount)")
            }
        } catch {
            FileHandle.standardError.write(Data("Example failed: \(error)\n".utf8))
            exit(EXIT_FAILURE)
        }
    }

    enum ExampleError: Error {
        case sessionDisappeared
    }
}

Build and run the saved program. An operation or cleanup error produces a failing exit status. Set LIBTMUX_TMUX_BIN to an absolute executable path to select a tmux version:

$ swift run ApiExample

Expected output:

Created: work
Original windows: 1
Current windows: 2

Parameters

named (String) #
startDirectory (String?) #
windowName (String?) #
width (Int?) #
height (Int?) #
environment ([String: String]) #
shell (String?) #

Raises

TmuxError

tmux command#

The tmux commands behind newSession(named:startDirectory:windowName:width:height:environment:shell:).

new-session resize-window (the requested size differs from the created size)

tmux C API#

The C declarations in tmux that implement these commands.

cmd_new_session_entry cmd_new_session_exec cmd_resize_window_entry cmd_resize_window_exec

Each path starts at a function a command runs, which is degree 1. The degree counts steps from there along the path, and each step is a call or a reference: degree 2 is reached from that function, degree 3 from the next, and so on.

Create a session and its first pane

In other ports#

Create a session

Equivalents of Create a session in other languages
Language	Equivalent
Python	`libtmux.Server.new_session`
Ruby	`LibTmux::Server#new_session`
Lua	`libtmux.Server:new_session`
Erlang	`tmux_session:create/2`
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
TypeScript	`server.Server.newSession`
Rust	`server.Server.new_session`
Go	`tmux.Server.NewSession`
Java	`io.github.libtmux.Server.newSession`
Clojure	`libtmux.core/new-session!`
Kotlin	`io.github.libtmux.kotlin.Server.newSession`
Scala	`io.github.libtmux.scaladsl.Server.newSession`
C#	`LibTmux.Server.CreateSessionAsync`
C++	`libtmux::Server::new_session`
OCaml	`Libtmux_unix.Client.create_session`
Perl	`LibTmux::Server::new_session` Explicit Server operation. Captured entities remain local observations; use a new snapshot to observe changes.

No equivalent is recorded in PowerShell, Julia, Elixir, Common Lisp or F#.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Server.newSession(named:startDirectory:windowName:width:height:environment:shell:)

Description#

Examples#

tmux command#

tmux C API#

Create a session and its first pane

In other ports#

Description#

Examples#

tmux command#

tmux C API#

Create a session and its first pane

In other ports#

Related types#