@tauri-apps/plugin-shell

Access the system shell. Allows you to spawn child processes and manage files and URLs using their default application.

Security

This API has a scope configuration that forces you to restrict the programs and arguments that can be used.

Restricting access to the `open` API

On the configuration object, open: true means that the open API can be used with any URL, as the argument is validated with the ^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+ regex. You can change that regex by changing the boolean value to a string, e.g. open: ^https://github.com/.

Restricting access to the `Command` APIs

The plugin permissions object has a scope field that defines an array of CLIs that can be used. Each CLI is a configuration object { name: string, cmd: string, sidecar?: bool, args?: boolean | Arg[] }.

name: the unique identifier of the command, passed to the Command.create function. If it’s a sidecar, this must be the value defined on tauri.conf.json > bundle > externalBin.
cmd: the program that is executed on this configuration. If it’s a sidecar, this value is ignored.
sidecar: whether the object configures a sidecar or a system program.
args: the arguments that can be passed to the program. By default no arguments are allowed.
- true means that any argument list is allowed.
- false means that no arguments are allowed.
- otherwise an array can be configured. Each item is either a string representing the fixed argument value or a { validator: string } that defines a regex validating the argument value.

Example scope configuration

CLI: git commit -m "the commit message"

Capability:

{
  "permissions": [
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "name": "run-git-commit",
          "cmd": "git",
          "args": ["commit", "-m", { "validator": "\\S+" }]
        }
      ]
    }
  ]
}

Usage:

import { Command } from '@tauri-apps/plugin-shell'
Command.create('run-git-commit', ['commit', '-m', 'the commit message'])

Trying to execute any API with a program not configured on the scope results in a promise rejection due to denied access.

Classes

Child

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L437

A handle to a child process spawned with Command.spawn, which can be used to write to its stdin or to kill it.

Since

2.0.0

Constructors

Constructor

new Child(pid): Child;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L456

Creates a handle to the child process with the given process id.

Parameters

Parameter	Type	Description
`pid`	`number`	The process id of the child process.

Returns

Child

Example

import { Command } from '@tauri-apps/plugin-shell';
// a `Child` is usually obtained by spawning a command:
const child = await Command.create('node').spawn();
console.log(child.pid);

Since

2.0.0

Properties

Property	Type	Description	Defined in
`pid`	`number`	The child process `pid`.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L439

Methods

kill()

kill(): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L499

Kills the child process.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const child = await command.spawn();
await child.kill();

Since

2.0.0

write()

write(data): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L477

Writes data to the stdin.

Parameters

Parameter	Type	Description
`data`	`IOPayload` \| `number`[]	The message to write, either a string or a byte array.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const child = await command.spawn();
await child.write('message');
await child.write([0, 1, 2, 3, 4, 5]);

Since

2.0.0

Command

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L550

The entry point for spawning child processes. It emits the close and error events.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('close', data => {
  console.log(`command finished with code ${data.code} and signal ${data.signal}`)
});
command.on('error', error => console.error(`command error: "${error}"`));
command.stdout.on('data', line => console.log(`command stdout: "${line}"`));
command.stderr.on('data', line => console.log(`command stderr: "${line}"`));

const child = await command.spawn();
console.log('pid:', child.pid);

Since

2.0.0

Extends

EventEmitter<CommandEvents>

Type Parameters

Type Parameter
`O` extends `IOPayload`

Properties

Property	Modifier	Type	Description	Defined in
`stderr`	`readonly`	`EventEmitter`<`OutputEvents`<`O`>>	Event emitter for the `stderr`. Emits the `data` event.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L560
`stdout`	`readonly`	`EventEmitter`<`OutputEvents`<`O`>>	Event emitter for the `stdout`. Emits the `data` event.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L558

Methods

addListener()

addListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L137

Alias for emitter.on(eventName, listener).

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.addListener('error', (error) => console.error(error));

Since

2.0.0

Inherited from

EventEmitter.addListener

execute()

execute(): Promise<ChildProcess<O>>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L839

Executes the command as a child process, waiting for it to finish and collecting all of its output.

Returns

Promise<ChildProcess<O>>

A promise resolving to the child process output.

Example

import { Command } from '@tauri-apps/plugin-shell';
const output = await Command.create('echo', 'message').execute();
assert(output.code === 0);
assert(output.signal === null);
assert(output.stdout === 'message');
assert(output.stderr === '');

Since

2.0.0

listenerCount()

listenerCount<N>(eventName): number;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L354

Returns the number of listeners listening to the event named eventName.

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to count the listeners of.

Returns

number

The number of listeners registered for the given event.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('close', () => {});
console.log(command.listenerCount('close')); // 1

Since

2.0.0

Inherited from

EventEmitter.listenerCount

off()

off<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L261

Removes the all specified listener from the listener array for the event eventName Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to stop listening to.
`listener`	(`arg`) => `void`	The exact callback that was registered before.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const listener = (error: string) => console.error(error);
command.on('error', listener);
command.off('error', listener);

Since

2.0.0

Inherited from

EventEmitter.off

on()

on<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L194

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventNameand listener will result in the listener being added, and called, multiple times.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('close', (data) => {
  console.log(`command finished with code ${data.code}`);
});

Since

2.0.0

Inherited from

EventEmitter.on

once()

once<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L230

Adds a one-timelistener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to once.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.once('close', (data) => {
  console.log(`command finished with code ${data.code}`);
});

Since

2.0.0

Inherited from

EventEmitter.once

prependListener()

prependListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L383

Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventNameand listener will result in the listener being added, and called, multiple times.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.prependListener('error', (error) => console.error(error));

Since

2.0.0

Inherited from

EventEmitter.prependListener

prependOnceListener()

prependOnceListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L417

Adds a one-timelistener function for the event named eventName to the_beginning_ of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to once.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.prependOnceListener('error', (error) => console.error(error));

Since

2.0.0

Inherited from

EventEmitter.prependOnceListener

removeAllListeners()

removeAllListeners<N>(event?): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L294

Removes all listeners, or those of the specified eventName.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`event?`	`N`	The name of the event to remove the listeners of. When omitted, the listeners of every event are removed.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('error', (error) => console.error(error));
command.removeAllListeners('error');

Since

2.0.0

Inherited from

EventEmitter.removeAllListeners

removeListener()

removeListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L163

Alias for emitter.off(eventName, listener).

Type Parameters

Type Parameter
`N` extends keyof `CommandEvents`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to stop listening to.
`listener`	(`arg`) => `void`	The exact callback that was registered before.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const listener = (error: string) => console.error(error);
command.addListener('error', listener);
command.removeListener('error', listener);

Since

2.0.0

Inherited from

EventEmitter.removeListener

spawn()

spawn(): Promise<Child>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L788

Executes the command as a child process, returning a handle to it.

Returns

Promise<Child>

A promise resolving to the child process handle.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.stdout.on('data', (line) => console.log(line));
const child = await command.spawn();
console.log('pid:', child.pid);

Since

2.0.0

create()

Creates a command to execute the given program.

Param

program

The program to execute. It must be configured in your project’s capabilities.

Param

args

The arguments to pass to the program. Defaults to no arguments.

Param

options

Spawn options such as the working directory, the environment variables and the character encoding of the process output.

Since

2.0.0

Call Signature

static create(program, args?): Command<string>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L600

Creates a command to execute the given program, decoding its output as text.

Parameters

Parameter	Type	Description
`program`	`string`	The program to execute. It must be configured in your project’s capabilities.
`args?`	`string` \| `string`[]	The arguments to pass to the program. Defaults to no arguments.

Returns

Command<string>

The command instance, ready to be spawned or executed.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();

Since

2.0.0

Call Signature

static create(
   program,
   args?,
   options?
): Command<Uint8Array<ArrayBufferLike>>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L622

Creates a command to execute the given program, keeping its output as raw bytes.

Parameters

Parameter	Type	Description
`program`	`string`	The program to execute. It must be configured in your project’s capabilities.
`args?`	`string` \| `string`[]	The arguments to pass to the program. Defaults to no arguments.
`options?`	`SpawnOptions` & `object`	Spawn options using the `raw` encoding, which makes the process output be delivered as `Uint8Array` instead of `string`.

Returns

Command<Uint8Array<ArrayBufferLike>>

The command instance, ready to be spawned or executed.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri'], { encoding: 'raw' });
const output = await command.execute();
console.log(output.stdout); // a Uint8Array

Since

2.0.0

Call Signature

static create(
   program,
   args?,
   options?
): Command<string>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L647

Creates a command to execute the given program with the given spawn options.

Parameters

Parameter	Type	Description
`program`	`string`	The program to execute. It must be configured in your project’s capabilities.
`args?`	`string` \| `string`[]	The arguments to pass to the program. Defaults to no arguments.
`options?`	`SpawnOptions`	Spawn options such as the working directory, the environment variables and the character encoding of the process output.

Returns

Command<string>

The command instance, ready to be spawned or executed.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri'], { cwd: '/path/to/project' });
const output = await command.execute();

Since

2.0.0

sidecar()

Creates a command to execute the given sidecar program.

Param

program

The sidecar program to execute. It must be configured in your project’s capabilities and defined on tauri.conf.json > bundle > externalBin.

Param

args

The arguments to pass to the program. Defaults to no arguments.

Param

options

Spawn options such as the working directory, the environment variables and the character encoding of the process output.

Since

2.0.0

Call Signature

static sidecar(program, args?): Command<string>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L693

Creates a command to execute the given sidecar program, decoding its output as text.

Parameters

Parameter	Type	Description
`program`	`string`	The sidecar program to execute. It must be configured in your project’s capabilities and defined on `tauri.conf.json > bundle > externalBin`.
`args?`	`string` \| `string`[]	The arguments to pass to the program. Defaults to no arguments.

Returns

Command<string>

The command instance, ready to be spawned or executed.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();

Since

2.0.0

Call Signature

static sidecar(
   program,
   args?,
   options?
): Command<Uint8Array<ArrayBufferLike>>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L716

Creates a command to execute the given sidecar program, keeping its output as raw bytes.

Parameters

Parameter	Type	Description
`program`	`string`	The sidecar program to execute. It must be configured in your project’s capabilities and defined on `tauri.conf.json > bundle > externalBin`.
`args?`	`string` \| `string`[]	The arguments to pass to the program. Defaults to no arguments.
`options?`	`SpawnOptions` & `object`	Spawn options using the `raw` encoding, which makes the process output be delivered as `Uint8Array` instead of `string`.

Returns

Command<Uint8Array<ArrayBufferLike>>

The command instance, ready to be spawned or executed.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar', [], { encoding: 'raw' });
const output = await command.execute();
console.log(output.stdout); // a Uint8Array

Since

2.0.0

Call Signature

static sidecar(
   program,
   args?,
   options?
): Command<string>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L742

Creates a command to execute the given sidecar program with the given spawn options.

Parameters

Parameter	Type	Description
`program`	`string`	The sidecar program to execute. It must be configured in your project’s capabilities and defined on `tauri.conf.json > bundle > externalBin`.
`args?`	`string` \| `string`[]	The arguments to pass to the program. Defaults to no arguments.
`options?`	`SpawnOptions`	Spawn options such as the working directory, the environment variables and the character encoding of the process output.

Returns

Command<string>

The command instance, ready to be spawned or executed.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar', [], { cwd: '/path/to/project' });
const output = await command.execute();

Since

2.0.0

EventEmitter

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L114

A minimal event emitter modeled after Node.js’ EventEmitter, used by Command and by its stdout and stderr streams.

Since

2.0.0

Extended by

Command

Type Parameters

Type Parameter
`E` extends `Record`<`string`, `any`>

Constructors

Constructor

new EventEmitter<E>(): EventEmitter<E>;

Returns

EventEmitter<E>

Methods

addListener()

addListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L137

Alias for emitter.on(eventName, listener).

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.addListener('error', (error) => console.error(error));

Since

2.0.0

listenerCount()

listenerCount<N>(eventName): number;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L354

Returns the number of listeners listening to the event named eventName.

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to count the listeners of.

Returns

number

The number of listeners registered for the given event.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('close', () => {});
console.log(command.listenerCount('close')); // 1

Since

2.0.0

off()

off<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L261

Removes the all specified listener from the listener array for the event eventName Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to stop listening to.
`listener`	(`arg`) => `void`	The exact callback that was registered before.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const listener = (error: string) => console.error(error);
command.on('error', listener);
command.off('error', listener);

Since

2.0.0

on()

on<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L194

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('close', (data) => {
  console.log(`command finished with code ${data.code}`);
});

Since

2.0.0

once()

once<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L230

Adds a one-timelistener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to once.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.once('close', (data) => {
  console.log(`command finished with code ${data.code}`);
});

Since

2.0.0

prependListener()

prependListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L383

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.prependListener('error', (error) => console.error(error));

Since

2.0.0

prependOnceListener()

prependOnceListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L417

Adds a one-timelistener function for the event named eventName to the_beginning_ of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to listen to once.
`listener`	(`arg`) => `void`	The callback invoked with the event payload.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.prependOnceListener('error', (error) => console.error(error));

Since

2.0.0

removeAllListeners()

removeAllListeners<N>(event?): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L294

Removes all listeners, or those of the specified eventName.

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`event?`	`N`	The name of the event to remove the listeners of. When omitted, the listeners of every event are removed.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('error', (error) => console.error(error));
command.removeAllListeners('error');

Since

2.0.0

removeListener()

removeListener<N>(eventName, listener): this;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L163

Alias for emitter.off(eventName, listener).

Type Parameters

Type Parameter
`N` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`eventName`	`N`	The name of the event to stop listening to.
`listener`	(`arg`) => `void`	The exact callback that was registered before.

Returns

this

A reference to the EventEmitter, so that calls can be chained.

Example

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const listener = (error: string) => console.error(error);
command.addListener('error', listener);
command.removeListener('error', listener);

Since

2.0.0

Interfaces

ChildProcess

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L96

The output collected from a child process that ran to completion.

Since

2.0.0

Type Parameters

Type Parameter
`O` extends `IOPayload`

Properties

Property	Type	Description	Defined in
`code`	`number` \| `null`	Exit code of the process. `null` if the process was terminated by a signal on Unix.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L98
`signal`	`number` \| `null`	If the process was terminated by a signal, represents that signal.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L100
`stderr`	`O`	The data that the process wrote to `stderr`.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L104
`stdout`	`O`	The data that the process wrote to `stdout`.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L102

CommandEvents

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L512

The events emitted by a Command instance.

Since

2.0.0

Properties

Property	Type	Description	Defined in
`close`	`TerminatedPayload`	Emitted when the child process terminated, carrying its exit code and signal.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L514
`error`	`string`	Emitted when the child process could not be spawned or failed unexpectedly, carrying the error message.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L516

OutputEvents

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L524

The events emitted by the stdout and stderr streams of a Command.

Since

2.0.0

Type Parameters

Type Parameter
`O` extends `IOPayload`

Properties

Property	Type	Description	Defined in
`data`	`O`	Emitted for each line the process wrote to the stream, or for each raw chunk when the `raw` encoding is used.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L526

SpawnOptions

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L73

Options that configure how a child process is spawned.

Since

2.0.0

Properties

Property	Type	Description	Defined in
`cwd?`	`string`	Current working directory.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L75
`encoding?`	`string`	Character encoding for stdout/stderr Since 2.0.0	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L83
`env?`	`Record`<`string`, `string`>	Environment variables. set to `null` to clear the process env.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L77

TerminatedPayload

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L867

Payload for the Terminated command event.

Properties

Property	Type	Description	Defined in
`code`	`number` \| `null`	Exit code of the process. `null` if the process was terminated by a signal on Unix.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L869
`signal`	`number` \| `null`	If the process was terminated by a signal, represents that signal.	Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L871

Type Aliases

IOPayload

type IOPayload =
  | string
  | Uint8Array;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L878

The type of the data a child process writes to stdout and stderr: a string, or a Uint8Array when the raw encoding is configured.

Functions

open()

function open(path, openWith?): Promise<void>;

Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L913

Opens a path or URL with the system’s default app, or the one specified with openWith.

The openWith value must be one of firefox, google chrome, chromium safari, open, start, xdg-open, gio, gnome-open, kde-open or wslview.

Parameters

Parameter	Type	Description
`path`	`string`	The path or URL to open. This value is matched against the string regex defined on `tauri.conf.json > plugins > shell > open`, which defaults to `^((mailto:\w+)
`openWith?`	`string`	The app to open the file or URL with. Defaults to the system default application for the specified path type.

Returns

Promise<void>

Example

import { open } from '@tauri-apps/plugin-shell';
// opens the given URL on the default browser:
await open('https://github.com/tauri-apps/tauri');
// opens the given URL using `firefox`:
await open('https://github.com/tauri-apps/tauri', 'firefox');
// opens a file using the default program:
await open('/path/to/file');

Since

2.0.0

Support on Open Collective Sponsor on GitHub