Arcane.terminal.write()

This focused page is derived from the mechanically checked full member inventory.

Syntax

Arcane.terminal.write(sessionId, data)

Parameters

sessionId: 1–128-character session identifier; data: 1–65,536 UTF-8 bytes

Return value

Promise<{sessionId,accepted:true,bytes}>

Description

Writes one input chunk. Output is delivered separately through terminal.output, so subscribe before starting a session and correlate chunks by sessionId.

Overview

Arcane.terminal.write(sessionId, data) writes one nonempty UTF-8 input chunk to a running app-owned session. The method is non-idempotent: after an ambiguous timeout or transport failure, do not retry blindly because the first input may already have reached the process.

The method does not append a line ending. Use "\r\n" for PowerShell or Command Prompt and "\n" for POSIX shells when the target shell should submit a command. It also does not return process output or command completion; subscribe to terminal.output and terminal.exit before writing.

Output events contain stream chunks, not lines. Preserve per-session arrival order and expect a chunk to contain partial text, multiple lines, or terminal control sequences.

Input

The JavaScript wrapper converts sessionId and data to strings. An empty value is still invalid, and the limit is measured in UTF-8 bytes rather than JavaScript characters.

Acceptance result

The method resolves to:

const result = {
    sessionId: 'term-example',
    accepted: true,
    bytes: 21
};

bytes is the accepted UTF-8 byte count, from 1 through 65,536. accepted means the host accepted the input for the session; it does not mean the shell finished a command.

Errors and recovery

Example

const terminal = globalThis.Arcane?.terminal;
const events = globalThis.Arcane?.events;

if (!terminal?.write || !terminal?.list || !events?.on) {
    throw new Error('Native terminal input is unavailable.');
}

const {sessions} = await terminal.list();
const session = sessions[0];

if (!session) {
    throw new Error('Start a terminal session before writing input.');
}

const offOutput = events.on('terminal.output', function handleTerminalOutput(payload) {
    if (payload.sessionId === session.id) {
        console.log(payload.stream, payload.data);
    }
});

try {
    const lineEnding = ['powershell', 'cmd'].includes(session.shell)
        ? '\r\n'
        : '\n';
    const result = await terminal.write(
        session.id,
        `echo Input was accepted${lineEnding}`
    );
    console.log(`Accepted ${result.bytes} UTF-8 bytes.`);
} catch (error) {
    if (error instanceof Arcane.Error) {
        console.error(error.code, error.message, error.resolution);
    } else {
        throw error;
    }
} finally {
    offOutput();
}

Reference group

Applications, terminal, and capabilities