> ## Documentation Index
> Fetch the complete documentation index at: https://dylankenneally-react-native-ssh-sftp-96.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell Operations

> Interactive shell session management.

export const EditThisPage = ({filePath}) => {
  const REPO_EDIT_BASE_URL = 'https://github.com/dylankenneally/react-native-ssh-sftp/edit/master';
  return <div className="mt-10 rounded-2xl border border-zinc-950/10 bg-zinc-50 px-4 py-3 dark:border-white/10 dark:bg-white/5">
      <p className="m-0 text-sm text-zinc-600 dark:text-zinc-300">
        See something to improve?{' '}
        <a href={`${REPO_EDIT_BASE_URL}/${filePath}`}>Edit this page on GitHub</a>{' '}
        to suggest a change.
      </p>
    </div>;
};

## Overview

Manage interactive shell sessions on the SSH server, allowing you to start shells, write commands, and handle shell output through events.

## startShell()

Starts an interactive shell session on the SSH server.

### Method Signature

```typescript theme={null}
startShell(ptyType: PtyType, callback?: CallbackFunction<string>): Promise<string>
```

### Parameters

<ParamField path="ptyType" type="PtyType" required>
  The type of pseudo-terminal to use for the shell session.

  **PtyType Enum Values:**

  ```typescript theme={null}
  enum PtyType {
    VANILLA = 'vanilla',
    VT100 = 'vt100',
    VT102 = 'vt102',
    VT220 = 'vt220',
    ANSI = 'ansi',
    XTERM = 'xterm'
  }
  ```

  * `VANILLA`: Basic terminal without special control sequences
  * `VT100`: DEC VT100 terminal emulation
  * `VT102`: DEC VT102 terminal emulation
  * `VT220`: DEC VT220 terminal emulation
  * `ANSI`: ANSI standard terminal
  * `XTERM`: XTerm terminal emulation (most common)
</ParamField>

<ParamField path="callback" type="CallbackFunction<string>" optional>
  Optional callback function to handle the response.

  **Type Definition:**

  ```typescript theme={null}
  type CallbackFunction<T> = (error: any, response?: T) => void
  ```
</ParamField>

### Return Value

<ResponseField name="Promise<string>" type="Promise<string>">
  Returns a Promise that resolves with the initial shell response.

  * **Resolves**: With the initial output from the shell session
  * **Rejects**: With an error if the shell session fails to start
  * **Note**: If a shell is already active, returns an empty string
</ResponseField>

### Usage Example

```typescript theme={null}
import SSHClient, { PtyType } from '@dylankenneally/react-native-ssh-sftp';

const client = await SSHClient.connectWithPassword(
  'example.com',
  22,
  'username',
  'password'
);

// Start a shell session
try {
  const response = await client.startShell(PtyType.XTERM);
  console.log('Shell started:', response);
} catch (error) {
  console.error('Failed to start shell:', error);
}
```

***

## writeToShell()

Writes a command to the active shell session.

### Method Signature

```typescript theme={null}
writeToShell(command: string, callback?: CallbackFunction<string>): Promise<string>
```

### Parameters

<ParamField path="command" type="string" required>
  The command to write to the shell.
</ParamField>

<ParamField path="callback" type="CallbackFunction<string>" optional>
  Optional callback function to handle the response.

  **Type Definition:**

  ```typescript theme={null}
  type CallbackFunction<T> = (error: any, response?: T) => void
  ```
</ParamField>

### Return Value

<ResponseField name="Promise<string>" type="Promise<string>">
  Returns a Promise that resolves with the response from the shell.

  * **Resolves**: With the shell output after executing the command
  * **Rejects**: With an error if the write operation fails
</ResponseField>

### Usage Example

```typescript theme={null}
// Write commands to the shell
try {
  const response1 = await client.writeToShell('cd /var/log');
  console.log('Response:', response1);

  const response2 = await client.writeToShell('ls -la');
  console.log('Directory listing:', response2);
} catch (error) {
  console.error('Shell write failed:', error);
}
```

### Notes

* Automatically starts a shell session with `PtyType.VANILLA` if one is not already active
* Commands are executed in the context of the active shell session
* State is maintained between calls (e.g., directory changes persist)

***

## closeShell()

Closes the active SSH shell session.

### Method Signature

```typescript theme={null}
closeShell(): void
```

### Parameters

None.

### Return Value

<ResponseField name="void" type="void">
  This method does not return a value.
</ResponseField>

### Usage Example

```typescript theme={null}
// Close the shell when done
client.closeShell();
console.log('Shell session closed');
```

### Notes

* Unregisters the 'Shell' event listener
* Sets the internal shell active state to false
* Should be called when you no longer need the shell session

***

## Shell Event

The 'Shell' event is emitted during shell operations to provide real-time output.

### Event Handler

Register a handler to receive shell output:

```typescript theme={null}
client.on('Shell', (data: any) => {
  console.log('Shell output:', data);
});
```

### Event Handler Type

```typescript theme={null}
type EventHandler = (value: any) => void
```

### Parameters

<ParamField path="value" type="any">
  The shell output data received from the server.
</ParamField>

### Usage Example

```typescript theme={null}
import SSHClient, { PtyType } from '@dylankenneally/react-native-ssh-sftp';

const client = await SSHClient.connectWithPassword(
  'example.com',
  22,
  'username',
  'password'
);

// Register shell event handler
client.on('Shell', (data) => {
  console.log('Real-time shell output:', data);
});

// Start shell and execute commands
await client.startShell(PtyType.XTERM);
await client.writeToShell('top');

// Clean up
client.closeShell();
```

### Removing a handler

Use `off()` (or its alias `removeListener()`) to remove a previously registered handler, for example when tearing down a component:

```typescript theme={null}
client.on('Shell', handleOutput);

// Later, stop receiving the event:
client.off('Shell');
// or, equivalently:
client.removeListener('Shell');
```

```typescript theme={null}
off(eventName: string): void
removeListener(eventName: string): void
```

<ParamField path="eventName" type="string" required>
  The name of the event whose handler should be removed (for example, `'Shell'`).
</ParamField>

### Notes

* The 'Shell' event listener is automatically registered when calling `startShell()`
* The event provides real-time output from the shell session
* The listener is automatically unregistered when calling `closeShell()`

***

## PtyType Enum

Defines the types of pseudo-terminals (PTY) available for SSH shell connections.

### Enum Definition

```typescript theme={null}
enum PtyType {
  VANILLA = 'vanilla',
  VT100 = 'vt100',
  VT102 = 'vt102',
  VT220 = 'vt220',
  ANSI = 'ansi',
  XTERM = 'xterm'
}
```

### Values

<ParamField path="VANILLA" type="'vanilla'">
  Basic terminal type without special control sequences. Use for simple command execution.
</ParamField>

<ParamField path="VT100" type="'vt100'">
  DEC VT100 terminal emulation. Classic terminal type with basic cursor control.
</ParamField>

<ParamField path="VT102" type="'vt102'">
  DEC VT102 terminal emulation. Enhanced version of VT100 with additional features.
</ParamField>

<ParamField path="VT220" type="'vt220'">
  DEC VT220 terminal emulation. Advanced terminal type with extended capabilities.
</ParamField>

<ParamField path="ANSI" type="'ansi'">
  ANSI standard terminal. Supports ANSI escape sequences for colors and formatting.
</ParamField>

<ParamField path="XTERM" type="'xterm'">
  XTerm terminal emulation. Most widely supported modern terminal type. **Recommended for most use cases.**
</ParamField>

### Usage Example

```typescript theme={null}
import { PtyType } from '@dylankenneally/react-native-ssh-sftp';

// Use the recommended XTERM type
await client.startShell(PtyType.XTERM);

// Or use VANILLA for simple cases
await client.startShell(PtyType.VANILLA);
```

<EditThisPage filePath="docs/api/ssh/shell.mdx" />