### session.shell

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Get a terminal shell on the given device. Returns a new or cached [_Shell](#_Shell) instance.

```APIDOC
## session.shell(nodeid, [unique])

### Description
Get a terminal shell on the given device.

### Parameters
#### Path Parameters
- **nodeid** (string) - Required - Unique id of node on which to open the shell

#### Query Parameters
- **unique** (boolean) - Optional - true: Create a unique [_Shell](#_Shell). Caller is responsible for cleanup. false: Use a cached [_Shell](#_Shell) if available, otherwise create and cache. Default: false

### Returns
- **Promise<_Shell>** - Newly created and initialized [_Shell](#_Shell) or cached [_Shell](#_Shell) if unique is false and a shell is currently active
```

--------------------------------

### session.list_user_groups

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Fetches user groups. Administrators can retrieve all user groups, while regular users get a limited set. Returns a promise that resolves to an array of group objects or null if no groups are found.

```APIDOC
## session.list_user_groups([timeout])

### Description
Get user groups. Admin will get all user groups, otherwise get limited user groups

### Method
N/A (Instance method, not HTTP)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **timeout** (number, optional) - duration in milliseconds to wait for a response before throwing an error

### Response
#### Success Response
- **(Array<Object> | null)** - List of groups, or null if no groups are found

### Throws
- **SocketError**: Info about socket closure
- **TimeoutError**: Command timed out
```

--------------------------------

### Create Session with Async/Await

Source: https://github.com/ylianst/libmeshctrl/blob/main/readme.md

Initialize a new session with the MeshCentral server using the static `create` function. This is the preferred method for asynchronous initialization.

```javascript
import { Session } from "LibMeshCtrl"
let session = await Session.create(url, {options})

session.list_users()
...
```

--------------------------------

### Session.create

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Creates a new Session instance to interact with devices.

```APIDOC
## Session.create

### Description
Creates a new Session instance.

### Method
static create(url, [options])

### Parameters
- **url** (string) - Required - The URL for the session.
- **options** (object) - Optional - Additional options for session creation.
```

--------------------------------

### Session Constructor

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Initializes a new Session instance to connect to a Meshcentral server.

```APIDOC
## new Session(url, [options])

### Description
Constructor for Session. Establishes a connection to a Meshcentral server.

### Parameters
#### Path Parameters
- **url** (string) - Required - URL of meshcentral server to connect to. Should start with either "ws://" or "wss://".

#### Query Parameters
- **options** (Object) - Optional - Optional arguments for instantiation.
  - **user** (string) - Optional - Username of to use for connecting. Can also be username generated from token.
  - **domain** (string) - Optional - Domain to connect to.
  - **password** (string) - Optional - Password with which to connect. Can also be password generated from token.
  - **loginkey** (string) - Optional - Key from already handled login. Overrides username/password.
  - **proxy** (string) - Optional - "url:port" to use for proxy server.
  - **token** (string) - Optional - Login token. This appears to be superfluous.
  - **ignoreSSL** (string) - Optional - Ignore SSL errors.

### Returns
- [<code>Session</code>](#Session) - Instance of Session
```

--------------------------------

### session.file_explorer

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Create, initialize, and return an _File object for the given node

```APIDOC
## session.file_explorer(nodeid, [unique])

### Description
Create, initialize, and return an _File object for the given node

### Method
instance method of [Session](#Session)

### Parameters
#### Path Parameters
- **nodeid** (string) - Required - Unique id on which to open file explorer
- **unique** (boolean) - Optional - true: Create a unique [_Files](#_Files). Caller is responsible for cleanup. false: Use a cached [_Files](#_Files) if available, otherwise create and cache. Default: false

### Returns
- **Promise<_Files>** - A newly initialized file explorer.
```

--------------------------------

### Session.create

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Factory for Session

```APIDOC
## Session.create(url, [options])

### Description
Factory for Session

### Method
static method of [Session](#Session)

### Parameters
#### Path Parameters
- **url** (string) - Required - URL of meshcentral server to connect to. Should start with either "ws://" or "wss://".
- **options** (Object) - Optional - Optional arguments for instantiation. Default: {}
  - **options.user** (string) - Optional - Username of to use for connecting. Can also be username generated from token. Default: null
  - **options.domain** (string) - Optional - Domain to connect to. Default: null
  - **options.password** (string) - Optional - Password with which to connect. Can also be password generated from token. Default: null
  - **options.loginkey** (string) - Optional - Key from already handled login. Overrides username/password. Default: null
  - **options.proxy** (string) - Optional - "url:port" to use for proxy server. Default: null
  - **options.token** (string) - Optional - Login token. This appears to be superfluous. Default: null

### Returns
- **Session** - Instance of Session which has been initialized
```

--------------------------------

### _Shell.create

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Factory method to create a new _Shell instance.

```APIDOC
## _Shell.create(session, node_id)

### Description
Constructor for _Shell.

### Method
Static method of _Shell

### Parameters
#### Path Parameters
- **session** (Session) - Required - Session representing a logged in user
- **node_id** (string) - Required - Node on which to open the shell

### Returns
- **_Shell** - Instance of _Shell
```

--------------------------------

### Session.wake_devices

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Wakes up specified devices.

```APIDOC
## Session.wake_devices

### Description
Wakes up one or more devices.

### Method
.wake_devices(nodeids, [timeout])

### Parameters
- **nodeids** (Array<string>) - Required - An array of node IDs to wake up.
- **timeout** (number) - Optional - The timeout in milliseconds.
```

--------------------------------

### Session.smart_shell

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Opens a smart shell on a specified node.

```APIDOC
## Session.smart_shell

### Description
Opens a smart shell on a specified node, optionally filtering by a regex and ensuring uniqueness.

### Method
.smart_shell(nodeid, regex, [unique])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **regex** (string) - Required - A regular expression to filter shell output.
- **unique** (boolean) - Optional - If true, ensures a unique shell session.
```

--------------------------------

### Session Class Methods

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

This section outlines the various instance methods available on the Session class for interacting with MeshCentral.

```APIDOC
## Session Class Instance Methods

### `.close()`

Closes the current session.

### `.server_info()`

Retrieves information about the server.

Returns: `Promise<Object>` - An object containing server information.

### `.user_info()`

Retrieves information about the current user.

Returns: `Promise<Object>` - An object containing user information.

### `.send_invite_email(group, email, [options], [timeout])`

Sends an invitation email to a specified group and email address.

Parameters:
- `group` (string): The group to invite.
- `email` (string): The email address to send the invitation to.
- `options` (object, optional): Additional options for the invitation.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the email was sent successfully, false otherwise.

### `.generate_invite_link(group, hours, [options], [timeout])`

Generates an invitation link for a specified group.

Parameters:
- `group` (string): The group for which to generate the link.
- `hours` (number): The duration in hours for which the link will be valid.
- `options` (object, optional): Additional options for the link.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Object>` - An object containing the invitation link details.

### `.list_users([timeout])`

Lists all users in the system.

Parameters:
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<Object>>` - An array of user objects.

### `.list_user_sessions([timeout])`

Lists all active user sessions.

Parameters:
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<Object>>` - An array of user session objects.

### `.list_user_groups([timeout])`

Lists all user groups.

Parameters:
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<(Array<Object>|null)>` - An array of user group objects or null if an error occurs.

### `.list_device_groups([timeout])`

Lists all device groups.

Parameters:
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<Object>>` - An array of device group objects.

### `.list_devices([options], [timeout])`

Lists all devices, optionally filtered by options.

Parameters:
- `options` (object, optional): Filtering options for devices.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<Object>>` - An array of device objects.

### `.on_close(f)`

Registers a callback function to be executed when the session is closed.

Parameters:
- `f` (function): The callback function.

### `.listen_to_events(f, [filter])`

Starts listening to session events.

Parameters:
- `f` (function): The callback function to handle events.
- `filter` (object, optional): A filter to apply to events.

Returns: `function` - A function to stop listening to events.

### `.stop_listening_to_events(Callback)`

Stops listening to session events.

Parameters:
- `Callback` (function): The callback function that was registered with `listen_to_events`.

### `.list_events([options], [timeout])`

Lists session events.

Parameters:
- `options` (object, optional): Filtering options for events.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<Object>>` - An array of event objects.

### `.list_login_tokens([timeout])`

Lists all login tokens.

Parameters:
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<Object>>` - An array of login token objects.

### `.add_login_token(name, [expire], [timeout])`

Adds a new login token.

Parameters:
- `name` (string): The name of the token.
- `expire` (number, optional): The expiration time in seconds.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Object>` - An object representing the newly created login token.

### `.remove_login_token(name, [timeout])`

Removes a login token by name.

Parameters:
- `name` (string): The name of the token to remove.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<Object>>` - An array of remaining login token objects.

### `.add_user(name, password, [options], [timeout])`

Adds a new user to the system.

Parameters:
- `name` (string): The username.
- `password` (string): The user's password.
- `options` (object, optional): Additional options for the user.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the user was added successfully, false otherwise.

### `.edit_user(userid, [options], [timeout])`

Edits an existing user.

Parameters:
- `userid` (string): The ID of the user to edit.
- `options` (object, optional): The updated user information.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the user was edited successfully, false otherwise.

### `.remove_user(userid, [timeout])`

Removes a user by their ID.

Parameters:
- `userid` (string): The ID of the user to remove.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the user was removed successfully, false otherwise.

### `.add_user_group(name, [description], [timeout])`

Adds a new user group.

Parameters:
- `name` (string): The name of the user group.
- `description` (string, optional): A description for the group.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Object>` - An object representing the newly created user group.

### `.remove_user_group(userid, [timeout])`

Removes a user group by its ID.

Parameters:
- `userid` (string): The ID of the user group to remove.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the user group was removed successfully, false otherwise.

### `.add_users_to_user_group(ids, groupid, [timeout])`

Adds users to a user group.

Parameters:
- `ids` (Array<string>): An array of user IDs to add.
- `groupid` (string): The ID of the user group.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Array<string>>` - An array of user IDs that were successfully added.

### `.remove_user_from_user_group(id, groupid, [timeout])`

Removes a user from a user group.

Parameters:
- `id` (string): The ID of the user to remove.
- `groupid` (string): The ID of the user group.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the user was removed successfully, false otherwise.

### `.add_users_to_device(userids, nodeid, [rights], [timeout])`

Adds users to a device.

Parameters:
- `userids` (Array<string>): An array of user IDs to add.
- `nodeid` (string): The ID of the device.
- `rights` (object, optional): The rights to grant to the users.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the users were added successfully, false otherwise.

### `.remove_users_from_device(nodeid, userids, [timeout])`

Removes users from a device.

Parameters:
- `nodeid` (string): The ID of the device.
- `userids` (Array<string>): An array of user IDs to remove.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the users were removed successfully, false otherwise.

### `.add_device_group(name, [options], [timeout])`

Adds a new device group.

Parameters:
- `name` (string): The name of the device group.
- `options` (object, optional): Additional options for the device group.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Object>` - An object representing the newly created device group.

### `.remove_device_group(meshid, [isname], [timeout])`

Removes a device group.

Parameters:
- `meshid` (string): The ID or name of the device group to remove.
- `isname` (boolean, optional): True if `meshid` is a name, false if it is an ID.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the device group was removed successfully, false otherwise.

### `.edit_device_group(meshid, [options], [timeout])`

Edits an existing device group.

Parameters:
- `meshid` (string): The ID or name of the device group to edit.
- `options` (object, optional): The updated device group information.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the device group was edited successfully, false otherwise.

### `.move_to_device_group(nodeids, meshid, [isname], [timeout])`

Moves devices to a different device group.

Parameters:
- `nodeids` (Array<string>): An array of device IDs to move.
- `meshid` (string): The ID or name of the target device group.
- `isname` (boolean, optional): True if `meshid` is a name, false if it is an ID.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Boolean>` - True if the devices were moved successfully, false otherwise.

### `.add_users_to_device_group(userids, meshid, [options], [timeout])`

Adds users to a device group.

Parameters:
- `userids` (Array<string>): An array of user IDs to add.
- `meshid` (string): The ID or name of the device group.
- `options` (object, optional): Additional options.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<object>` - An object indicating the result of the operation.

### `.remove_users_from_device_group(userids, meshid, [isname], [timeout])`

Removes users from a device group.

Parameters:
- `userids` (Array<string>): An array of user IDs to remove.
- `meshid` (string): The ID or name of the device group.
- `isname` (boolean, optional): True if `meshid` is a name, false if it is an ID.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Object>` - An object indicating the result of the operation.

### `.broadcast(message, [userid], [timeout])`

Broadcasts a message to all connected clients or a specific user.

Parameters:
- `message` (string): The message to broadcast.
- `userid` (string, optional): The ID of the user to send the message to. If omitted, the message is broadcast to all.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<boolean>` - True if the broadcast was successful, false otherwise.

### `.device_info(nodeid, [timeout])`

Retrieves information about a specific device.

Parameters:
- `nodeid` (string): The ID of the device.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise` - A promise that resolves with the device information.

### `.edit_device(nodeid, [options], [timeout])`

Edits a device's properties.

Parameters:
- `nodeid` (string): The ID of the device to edit.
- `options` (object, optional): An object containing the properties to update.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<boolean>` - True if the device was edited successfully, false otherwise.

### `.run_command(nodeids, command, [options], [timeout])`

Runs a command on one or more devices.

Parameters:
- `nodeids` (Array<string>): An array of device IDs on which to run the command.
- `command` (string): The command to execute.
- `options` (object, optional): Options for running the command.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Object>` - An object containing the results of the command execution.

### `.run_console_command(nodeids, command, [options], [timeout])`

Runs a console command on one or more devices.

Parameters:
- `nodeids` (Array<string>): An array of device IDs on which to run the command.
- `command` (string): The console command to execute.
- `options` (object, optional): Options for running the command.
- `timeout` (number, optional): Timeout in milliseconds.

Returns: `Promise<Object>` - An object containing the results of the console command execution.

### `.shell(nodeid, [unique])`

Opens a shell session on a device.

Parameters:
- `nodeid` (string): The ID of the device.
- `unique` (boolean, optional): If true, ensures a unique shell session.

Returns: `Promise<_Shell>` - A promise that resolves with a `_Shell` object representing the shell session.
```

--------------------------------

### session.download_file

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Friendly wrapper around download to download to a filepath. Creates a WritableStream and calls download.

```APIDOC
## session.download_file(nodeid, source, filepath, [unique_file_tunnel])

### Description
Friendly wrapper around [download](#Session+download) to download to a filepath. Creates a WritableStream and calls download.

### Method
instance method of [Session](#Session)

### Parameters
#### Path Parameters
- **nodeid** (string) - Required - Unique id to download file from
- **source** (string) - Required - Path from which to download from device
- **filepath** (string) - Required - Path to which to download data
- **unique_file_tunnel** (boolean) - Optional - true: Create a unique [_Files](#_Files) for this call, which will be cleaned up on return, else use cached or cache [_Files](#_Files). Default: false

### Returns
- **Promise<WritableStream>** - The stream which has been downloaded into
```

--------------------------------

### _Shell.create

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Factory method to create a new _Shell instance for a given session and node.

```APIDOC
## _Shell.create(session, node_id)

### Description
Factory for _Shell. Creates an instance of _Shell which has been initialized.

### Parameters
#### Path Parameters
- **session** (_Session_) - Session representing a logged in user
- **node_id** (string) - Node on which to open the shell
```

--------------------------------

### _Files

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Class to control a virtual file explorer on a remote device.

```APIDOC
## _Files
Class to control a virtual file explorer on a remote device

**Kind**: global class
**Props**: <code>boolean</code> recorded - Whether the file session is being recored. Set in initialization.

* [_Files](#_Files)
    * [new _Files(session, node_id)](#new__Files_new)
    * _instance_
        * [.close()](#_Files+close)
        * [.ls(directory)](#_Files+ls)
        * [.mkdir(directory)](#_Files+mkdir)
        * [.rm(path, files, [recursive])](#_Files+rm)
        * [.rename(path, name, new_name)](#_Files+rename)
    * _static_
        * [.create(session, node_id)](#_Files.create)
```

```APIDOC
## new _Files(session, node_id)
Constructor for _Files

**Returns**: [<code>_Files</code>](#_Files) - Instance of _Files

| Param | Type | Description |
| --- | --- | --- |
| session | [<code>Session</code>](#Session) | Session representing a logged in user |
| node_id | <code>string</code> | Node on which to open the file explorer |
```

```APIDOC
## _Files.close()
Close underlying connection and invalidate any outstanding requests

**Kind**: instance method of [<code>_Files</code>](#_Files)
```

```APIDOC
## _Files.ls(directory) ⇒ <code>Promise.&lt;Array.&lt;Object&gt;&gt;</code>
Return a directory listing from the device

**Kind**: instance method of [<code>_Files</code>](#_Files)
**Returns**: <code>Promise.&lt;Array.&lt;Object&gt;&gt;</code> - - An array of objects representing the directory listing
**Throws**: [<code>SocketError</code>](#SocketError) Info about socket closure

| Param | Type | Description |
| --- | --- | --- |
| directory | <code>string</code> | Path to the directory you wish to list |
```

```APIDOC
## _Files.mkdir(directory) ⇒ <code>Promise.&lt;boolean&gt;</code>
Return a directory listing from the device

**Kind**: instance method of [<code>_Files</code>](#_Files)
**Returns**: <code>Promise.&lt;boolean&gt;</code> - - True if firectory creation succeeded
**Throws**: [<code>SocketError</code>](#SocketError) Info about socket closure

| Param | Type | Description |
| --- | --- | --- |
| directory | <code>string</code> | Path to the directory you wish to list |
```

```APIDOC
## _Files.rm(path, files, [recursive]) ⇒ <code>Promise.&lt;string&gt;</code>
Remove files/folder from the device. This API doesn't error if the file doesn't exist.

**Kind**: instance method of [<code>_Files</code>](#_Files)
**Returns**: <code>Promise.&lt;string&gt;</code> - - Message returned from server
**Throws**: [<code>ServerError</code>](#ServerError) Error text from server if there is a failure, [<code>SocketError</code>](#SocketError) Info about socket closure

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| path | <code>string</code> |  | Directory from which to delete files |
| files | <code>string</code> |  | Array of filenames to remove |
| [recursive] | <code>boolean</code> | <code>false</code> | Whether to delete the files recursively |
```

```APIDOC
## _Files.rename(path, name, new_name)

**Kind**: instance method of [<code>_Files</code>](#_Files)
```

```APIDOC
## _Files.create(session, node_id) ⇒ [<code>_Files</code>](#_Files)

**Kind**: static method of [<code>_Files</code>](#_Files)
**Returns**: [<code>_Files</code>](#_Files) - Instance of _Files
```

--------------------------------

### Session.device_open_url

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Opens a URL on a specified device.

```APIDOC
## Session.device_open_url

### Description
Opens a given URL on the specified device.

### Method
.device_open_url(nodeid, url, [timeout])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **url** (string) - Required - The URL to open.
- **timeout** (number) - Optional - The timeout in milliseconds.
```

--------------------------------

### session.download

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Download a file from a device into a writable stream. This creates an _File and destroys it every call. If you need to upload multiple files, use file_explorer instead.

```APIDOC
## session.download(nodeid, source, [target], [unique_file_tunnel])

### Description
Download a file from a device into a writable stream. This creates an _File and destroys it every call. If you need to upload multiple files, use [file_explorer](#Session+file_explorer) instead.

### Method
instance method of [Session](#Session)

### Parameters
#### Path Parameters
- **nodeid** (string) - Required - Unique id to download file from
- **source** (string) - Required - Path from which to download from device
- **target** (WritableStream) - Optional - Stream to which to write data. If null, create new PassThrough stream which is both readable and writable.
- **unique_file_tunnel** (boolean) - Optional - true: Create a unique [_Files](#_Files) for this call, which will be cleaned up on return, else use cached or cache [_Files](#_Files). Default: false

### Returns
- **Promise<WritableStream>** - The stream which has been downloaded into

### Throws
- **Error** String showing the intermediate outcome and how many bytes were downloaded
```

--------------------------------

### session.add_users_to_device

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Adds a user to an existing node. Returns a promise that resolves to true on success.

```APIDOC
## session.add_users_to_device(userids, nodeid, [rights], [timeout])

### Description
Add a user to an existing node.

### Method
instance method of Session

### Parameters
#### Path Parameters
- **userids** (string | array) - Required - Unique user id(s)
- **nodeid** (string) - Required - Node to add the given user to
- **[rights]** (MESHRIGHTS) - Optional - Bitwise mask for the rights on the given mesh
- **[timeout]** (number) - Optional - duration in milliseconds to wait for a response before throwing an error

### Returns
- **Promise<Boolean>** - true on success

### Throws
- **ServerError**: Error text from server if there is a failure
- **SocketError**: Info about socket closure
- **TimeoutError**: Command timed out
```

--------------------------------

### session.server_info()

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Retrieves information about the Meshcentral server.

```APIDOC
## session.server_info()

### Description
Get server information from the Meshcentral server.

### Method
instance method of [<code>Session</code>](#Session)

### Returns
- <code>Promise.&lt;Object&gt;</code> - Server info
```

--------------------------------

### Create Session with Initialized Property

Source: https://github.com/ylianst/libmeshctrl/blob/main/readme.md

Instantiate a new session object manually and wait for its `initialized` property to resolve. This is an alternative to the `create` function.

```javascript
let session = new Session(url, {options})
await session.initialized
```

--------------------------------

### Session.file_explorer

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Opens a file explorer interface on a specified node.

```APIDOC
## Session.file_explorer

### Description
Opens a file explorer interface on a specified node, optionally ensuring uniqueness.

### Method
.file_explorer(nodeid, [unique])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **unique** (boolean) - Optional - If true, ensures a unique file explorer instance.
```

--------------------------------

### session.smart_shell

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Establishes a smart terminal shell on a specified device. It can return a new shell or a cached one if available and unique is false.

```APIDOC
## session.smart_shell(nodeid, regex, [unique])

### Description
Get a smart terminal shell on the given device.

### Method
instance method of Session

### Parameters
#### Path Parameters
- **nodeid** (string) - Required - Unique id of node on which to open the shell
- **regex** (regex) - Required - Regex to watch for to signify that the shell is ready for new input.
- **unique** (boolean) - Optional - true: Create a unique _SmartShell. Caller is responsible for cleanup. false: Use a cached _SmartShell if available, otherwise create and cache. Defaults to false.

### Returns
- **Promise<_SmartShell>** - Newly created and initialized _SmartShell or cached _SmartShell if unique is false and a smartshell with regex is currently active
```

--------------------------------

### Session.list_device_shares

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Lists shares for a specific device.

```APIDOC
## Session.list_device_shares

### Description
Lists all active shares for a given device.

### Method
.list_device_shares(nodeid, [timeout])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **timeout** (number) - Optional - The timeout in milliseconds.
```

--------------------------------

### _SmartShell

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Wrapper around _Shell that uses regex to detect command completion.

```APIDOC
## _SmartShell
Wrapper around [_Shell](#_Shell) that tries to use a regex to detect when a command has finished running and the shell is ready for a new command

**Kind**: global class

* [_SmartShell](#_SmartShell)
    * [new _SmartShell(shell, regex)](#new__SmartShell_new)
    * [.send_command(command)](#_SmartShell+send_command)
    * [.close()](#_SmartShell+close)
```

```APIDOC
## new _SmartShell(shell, regex)
Constructor for _SmartShell

| Param | Type | Description |
| --- | --- | --- |
| shell | [<code>_Shell</code>](#_Shell) | The shell object to wrap with our smart shell |
| regex | <code>regex</code> | Regex to watch the terminal to signify a new command is ready |
```

```APIDOC
## _SmartShell.send_command(command) ⇒ <code>Promise.&lt;Buffer&gt;</code>
Send a command and wait for it to return

**Kind**: instance method of [<code>_SmartShell</code>](#_SmartShell)
**Returns**: <code>Promise.&lt;Buffer&gt;</code> - - Data received from command

| Param | Type | Description |
| --- | --- | --- |
| command | <code>string</code> | Command to write |
```

```APIDOC
## _SmartShell.close()
Close this smart shell and the underlying shell

**Kind**: instance method of [<code>_SmartShell</code>](#_SmartShell)
```

--------------------------------

### Session.download

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Downloads a file from a source on a device to a target.

```APIDOC
## Session.download

### Description
Downloads a file from a source path on a device to a target.

### Method
.download(nodeid, source, [target], [unique_file_tunnel])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **source** (string) - Required - The source path of the file on the device.
- **target** (string) - Optional - The target path for the downloaded file.
- **unique_file_tunnel** (boolean) - Optional - If true, uses a unique file tunnel.
```

--------------------------------

### _Files.create

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Factory method to create an instance of _Files for file operations.

```APIDOC
## _Files.create(session, node_id)

### Description
Factory for _Files.

### Method
Static method of _Files

### Parameters
#### Path Parameters
- **session** (Session) - Required - Session representing a logged in user
- **node_id** (string) - Required - Node on which to open the file explorer

### Returns
- **_Files** - Instance of _Files which has been initialized
```

--------------------------------

### session.add_login_token

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Create a login token for the current user. WARNING: Non namespaced call. Calling this function again before it returns may cause unintended consequences. Returns a Promise that resolves to the created token object. It can throw SocketError or TimeoutError.

```APIDOC
## session.add_login_token(name, [expire], [timeout]) ⇒ Promise&lt;Object&gt;

### Description
Create login token for current user. WARNING: Non namespaced call. Calling this function again before it returns may cause unintended consequences.

### Method
Instance method of `Session`

### Endpoint
`session.add_login_token`

### Parameters
#### Path Parameters
- **name** (string) - Required - Name of token.
- **expire** (number) - Optional - Minutes until expiration. 0 or null for no expiration.
- **timeout** (number) - Optional - Duration in milliseconds to wait for a response before throwing an error.

### Returns
- **Promise&lt;Object&gt;** - Created token

### Throws
- **SocketError** - Info about socket closure
- **TimeoutError** - Command timed out
```

--------------------------------

### Session.download_file

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Downloads a file from a device to a local filepath.

```APIDOC
## Session.download_file

### Description
Downloads a file from a source path on a device to a local file path.

### Method
.download_file(nodeid, source, filepath, [unique_file_tunnel])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **source** (string) - Required - The source path of the file on the device.
- **filepath** (string) - Required - The local file path to save the downloaded file.
- **unique_file_tunnel** (boolean) - Optional - If true, uses a unique file tunnel.
```

--------------------------------

### session.device_open_url

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Opens a specified URL in the default browser on the remote device. This is a non-namespaced call.

```APIDOC
## session.device_open_url(nodeid, url, [timeout])

### Description
Open url in browser on device. WARNING: Non namespaced call. Calling this function again before it returns may cause unintended consequences.

### Method
Not specified (likely asynchronous, returns Promise)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters Table
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| nodeid | string |  | Unique node from which to remove the share |
| url | string |  | url to open |
| [timeout] | number |  | duration in milliseconds to wait for a response before throwing an error |

### Response
#### Success Response
- **boolean**: true if successful

### Throws
- ServerError: Error text from server if there is a failure
- Error: `Failed to open url` if failure occurs
- SocketError: Info about socket closure
- TimeoutError: Command timed out
```

--------------------------------

### Session.add_device_share

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Adds a share to a specific device.

```APIDOC
## Session.add_device_share

### Description
Adds a new share to a device.

### Method
.add_device_share(nodeid, name, [options], [timeout])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **name** (string) - Required - The name of the share.
- **options** (object) - Optional - Additional options for the share.
- **timeout** (number) - Optional - The timeout in milliseconds.
```

--------------------------------

### Session.upload

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Uploads a file from a source to a target on a device.

```APIDOC
## Session.upload

### Description
Uploads a file from a source path to a target path on a device.

### Method
.upload(nodeid, source, target, [unique_file_tunnel])

### Parameters
- **nodeid** (string) - Required - The ID of the node.
- **source** (string) - Required - The source path of the file.
- **target** (string) - Required - The target path on the device.
- **unique_file_tunnel** (boolean) - Optional - If true, uses a unique file tunnel.
```

--------------------------------

### session.run_command

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Run a command on any number of nodes. WARNING: Non namespaced call. Calling this function again before it returns may cause unintended consequences.

```APIDOC
## session.run_command(nodeids, command, [options], [timeout])

### Description
Run a command on any number of nodes. WARNING: Non namespaced call. Calling this function again before it returns may cause unintended consequences.

### Parameters
#### Path Parameters
- **nodeids** (string | Array<string>) - Required - Unique ids of nodes on which to run the command
- **command** (string) - Required - Command to run

#### Query Parameters
- **options** (Object) - Optional - Default: {}
  - **powershell** (boolean) - Optional - Use powershell to run command. Only available on Windows. Default: false
  - **runasuser** (boolean) - Optional - Attempt to run as a user instead of the root permissions given to the agent. Fall back to root if we cannot. Default: false
  - **runasuseronly** (boolean) - Optional - Error if we cannot run the command as the logged in user. Default: false
- **timeout** (number) - Optional - duration in milliseconds to wait for a response before throwing an error

### Returns
- **Promise<Object>** - Object containing mapped output of the commands by device

### Throws
- **ServerError** - Error text from server if there is a failure
- **SocketError** - Info about socket closure
- **TimeoutError** - Command timed out
```

--------------------------------

### session.add_device_share

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Adds a device share to a specified node. This is a non-namespaced call and should be used with caution.

```APIDOC
## session.add_device_share(nodeid, name, [options], [timeout])

### Description
Add device share to given node. WARNING: Non namespaced call. Calling this function again before it returns may cause unintended consequences.

### Method
Not specified (likely asynchronous, returns Promise)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters Table
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| nodeid | string |  | Unique id of nodes of which to list shares |
| name | string |  | Name of guest with which to share |
| [options] | Object | {} |  |
| [options.type] | SHARINGTYPE | SHARINGTYPE.desktop | Type of share thise should be |
| [options.consent] | CONSENTFLAGS |  | Consent flags for share. Defaults to "notify" for your given SHARINGTYPE |
| [options.start] | number | new Date() | When to start the share |
| [options.end] | number |  | When to end the share. If null, use duration instead |
| [options.duration] | number | 60*60 | Duration in seconds for share to exist |
| [timeout] | number |  | duration in milliseconds to wait for a response before throwing an error |

### Response
#### Success Response
- **Object**: Info about the newly created share

### Throws
- ServerError: Error text from server if there is a failure
- SocketError: Info about socket closure
- TimeoutError: Command timed out
```

--------------------------------

### _Shell.write

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Writes a command string to the shell. The promise resolves when the data is sent, without verification.

```APIDOC
## _Shell.write(command)

### Description
Write to the shell.

### Method
Instance method of _Shell

### Parameters
#### Path Parameters
- **command** (string) - Required - String to write to the shell

### Returns
- **Promise** - Resolved when data is sent. No verification is performed.
```

--------------------------------

### session.list_device_shares

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Lists the shares for a given device node. This is a non-namespaced call and may have unintended consequences if called again before returning.

```APIDOC
## session.list_device_shares(nodeid, [timeout])

### Description
List device shares of given node. WARNING: Non namespaced call. Calling this function again before it returns may cause unintended consequences.

### Method
instance method of Session

### Parameters
#### Path Parameters
- **nodeid** (string) - Required - Unique id of nodes of which to list shares
- **timeout** (number) - Optional - duration in milliseconds to wait for a response before throwing an error

### Returns
- **Promise<Array<Object>>** - Array of objects representing device shares

### Throws
- **SocketError** - Info about socket closure
- **TimeoutError** - Command timed out
```

--------------------------------

### session.add_device_group

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Creates a new device group with specified options.

```APIDOC
## session.add_device_group(name, [options], [timeout])

### Description
Create a new device group.

### Method
instance method of Session

### Parameters
#### Path Parameters
- **name** (string) - Required - Name of device group

#### Query Parameters
- **options** (Object) - Optional - Options for the new device group
  - **description** (string) - Optional - Description of device group
  - **amtonly** (boolean) - Optional - If true, only allow authenticated devices
  - **features** (MESHFEATURES) - Optional - Bitwise features to enable on the group
  - **consent** (CONSENTFLAGS) - Optional - Bitwise consent flags to use for the group
- **timeout** (number) - Optional - duration in milliseconds to wait for a response before throwing an error

### Returns
- Promise<Object> - New device group

### Throws
- ServerError: Error text from server if there is a failure
- SocketError: Info about socket closure
- TimeoutError: Command timed out
```

--------------------------------

### session.upload

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Upload a stream to a device. This creates and destroys a temporary file on each call. For multiple file uploads, consider using file_explorer.

```APIDOC
## session.upload(nodeid, source, target, [unique_file_tunnel])

### Description
Upload a stream to a device. This creates an _File and destroys it every call. If you need to upload multiple files, use [file_explorer](#Session+file_explorer) instead.

### Method
instance method of [Session](#Session)

### Parameters
#### Path Parameters
- **nodeid** (string) - Required - Unique id to upload stream to
- **source** (ReadableStream) - Required - ReadableStream from which to read data
- **target** (string) - Required - Path which to upload stream to on remote device
- **[unique_file_tunnel]** (boolean) - Optional - true: Create a unique [_Files](#_Files) for this call, which will be cleaned up on return, else use cached or cache [_Files](#_Files), defaults to false

### Returns
- <code>Promise&lt;Object&gt;</code> - {result: bool whether upload succeeded, size: number of bytes uploaded}
```

--------------------------------

### session.wake_devices

Source: https://github.com/ylianst/libmeshctrl/blob/main/doc/api.md

Wakes up one or more specified devices. Returns true if successful, and can throw SocketError or TimeoutError.

```APIDOC
## session.wake_devices(nodeids, [timeout])

### Description
Wake up given devices.

### Method
instance method of Session

### Parameters
#### Path Parameters
- **nodeids** (string | Array<string>) - Required - Unique ids of nodes which to wake
- **timeout** (number) - Optional - duration in milliseconds to wait for a response before throwing an error

### Returns
- **Promise<boolean>** - True if successful

### Throws
- **SocketError** - Info about socket closure
- **TimeoutError** - Command timed out
```