@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

Defined in: plugins/shell/guest-js/index.ts:297

Since

2.0.0

Constructors

new Child()

new Child(pid): Child;

Defined in: plugins/shell/guest-js/index.ts:301

Parameters

Parameter	Type
pid	number

Returns

Child

Properties

Property	Type	Description	Defined in
pid	number	The child process pid.	plugins/shell/guest-js/index.ts:299

Methods

kill()

kill(): Promise<void>;

Defined in: plugins/shell/guest-js/index.ts:336

Kills the child process.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Since

2.0.0

write()

write(data): Promise<void>;

Defined in: plugins/shell/guest-js/index.ts:322

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

Defined in: plugins/shell/guest-js/index.ts:374

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.	plugins/shell/guest-js/index.ts:384
stdout	readonly	EventEmitter<OutputEvents<O>>	Event emitter for the stdout. Emits the data event.	plugins/shell/guest-js/index.ts:382

Methods

addListener()

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

Defined in: plugins/shell/guest-js/index.ts:118

Alias for emitter.on(eventName, listener).

Type Parameters

Type Parameter
N extends keyof CommandEvents

Parameters

Parameter	Type
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Inherited from

EventEmitter.addListener

execute()

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

Defined in: plugins/shell/guest-js/index.ts:530

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;

Defined in: plugins/shell/guest-js/index.ts:241

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

Type Parameters

Type Parameter
N extends keyof CommandEvents

Parameters

Parameter	Type
eventName	N

Returns

number

Since

2.0.0

Inherited from

EventEmitter.listenerCount

off()

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

Defined in: plugins/shell/guest-js/index.ts:186

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Inherited from

EventEmitter.off

on()

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

Defined in: plugins/shell/guest-js/index.ts:147

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Inherited from

EventEmitter.on

once()

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

Defined in: plugins/shell/guest-js/index.ts:169

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Inherited from

EventEmitter.once

prependListener()

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

Defined in: plugins/shell/guest-js/index.ts:258

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Inherited from

EventEmitter.prependListener

prependOnceListener()

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

Defined in: plugins/shell/guest-js/index.ts:280

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Inherited from

EventEmitter.prependOnceListener

removeAllListeners()

removeAllListeners<N>(event?): this;

Defined in: plugins/shell/guest-js/index.ts:206

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
event?	N

Returns

this

Since

2.0.0

Inherited from

EventEmitter.removeAllListeners

removeListener()

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

Defined in: plugins/shell/guest-js/index.ts:130

Alias for emitter.off(eventName, listener).

Type Parameters

Type Parameter
N extends keyof CommandEvents

Parameters

Parameter	Type
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Inherited from

EventEmitter.removeListener

spawn()

spawn(): Promise<Child>;

Defined in: plugins/shell/guest-js/index.ts:479

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

Returns

Promise<Child>

A promise resolving to the child process handle.

Since

2.0.0

create()

Creates a command to execute the given program.

Example

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

Param

program

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

Call Signature

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

Defined in: plugins/shell/guest-js/index.ts:406

Parameters

Parameter	Type
program	string
args?	string | string[]

Returns

Command<string>

Call Signature

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

Defined in: plugins/shell/guest-js/index.ts:407

Parameters

Parameter	Type
program	string
args?	string | string[]
options?	SpawnOptions & object

Returns

Command<Uint8Array>

Call Signature

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

Defined in: plugins/shell/guest-js/index.ts:412

Parameters

Parameter	Type
program	string
args?	string | string[]
options?	SpawnOptions

Returns

Command<string>

sidecar()

Creates a command to execute the given sidecar program.

Example

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

Param

program

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

Call Signature

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

Defined in: plugins/shell/guest-js/index.ts:438

Parameters

Parameter	Type
program	string
args?	string | string[]

Returns

Command<string>

Call Signature

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

Defined in: plugins/shell/guest-js/index.ts:439

Parameters

Parameter	Type
program	string
args?	string | string[]
options?	SpawnOptions & object

Returns

Command<Uint8Array>

Call Signature

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

Defined in: plugins/shell/guest-js/index.ts:444

Parameters

Parameter	Type
program	string
args?	string | string[]
options?	SpawnOptions

Returns

Command<string>

---

EventEmitter

Defined in: plugins/shell/guest-js/index.ts:107

Since

2.0.0

Extended by

• Command

Type Parameters

Type Parameter
E extends Record<string, any>

Constructors

new EventEmitter()

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

Returns

EventEmitter<E>

Methods

addListener()

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

Defined in: plugins/shell/guest-js/index.ts:118

Alias for emitter.on(eventName, listener).

Type Parameters

Type Parameter
N extends string | number | symbol

Parameters

Parameter	Type
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

listenerCount()

listenerCount<N>(eventName): number;

Defined in: plugins/shell/guest-js/index.ts:241

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

Type Parameters

Type Parameter
N extends string | number | symbol

Parameters

Parameter	Type
eventName	N

Returns

number

Since

2.0.0

off()

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

Defined in: plugins/shell/guest-js/index.ts:186

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

on()

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

Defined in: plugins/shell/guest-js/index.ts:147

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 string | number | symbol

Parameters

Parameter	Type
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

once()

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

Defined in: plugins/shell/guest-js/index.ts:169

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

prependListener()

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

Defined in: plugins/shell/guest-js/index.ts:258

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 string | number | symbol

Parameters

Parameter	Type
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

prependOnceListener()

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

Defined in: plugins/shell/guest-js/index.ts:280

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
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

removeAllListeners()

removeAllListeners<N>(event?): this;

Defined in: plugins/shell/guest-js/index.ts:206

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
event?	N

Returns

this

Since

2.0.0

removeListener()

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

Defined in: plugins/shell/guest-js/index.ts:130

Alias for emitter.off(eventName, listener).

Type Parameters

Type Parameter
N extends string | number | symbol

Parameters

Parameter	Type
eventName	N
listener	(arg) => void

Returns

this

Since

2.0.0

Interfaces

ChildProcess

Defined in: plugins/shell/guest-js/index.ts:92

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.	plugins/shell/guest-js/index.ts:94
signal	number | null	If the process was terminated by a signal, represents that signal.	plugins/shell/guest-js/index.ts:96
stderr	O	The data that the process wrote to stderr.	plugins/shell/guest-js/index.ts:100
stdout	O	The data that the process wrote to stdout.	plugins/shell/guest-js/index.ts:98

---

CommandEvents

Defined in: plugins/shell/guest-js/index.ts:344

Properties

Property	Type	Defined in
close	TerminatedPayload	plugins/shell/guest-js/index.ts:345
error	string	plugins/shell/guest-js/index.ts:346

---

OutputEvents

Defined in: plugins/shell/guest-js/index.ts:349

Type Parameters

Type Parameter
O extends IOPayload

Properties

Property	Type	Defined in
data	O	plugins/shell/guest-js/index.ts:350

---

SpawnOptions

Defined in: plugins/shell/guest-js/index.ts:71

Since

2.0.0

Properties

Property	Type	Description	Defined in
cwd?	string	Current working directory.	plugins/shell/guest-js/index.ts:73
encoding?	string	Character encoding for stdout/stderr Since 2.0.0	plugins/shell/guest-js/index.ts:81
env?	Record<string, string>	Environment variables. set to null to clear the process env.	plugins/shell/guest-js/index.ts:75

---

TerminatedPayload

Defined in: plugins/shell/guest-js/index.ts:558

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.	plugins/shell/guest-js/index.ts:560
signal	number | null	If the process was terminated by a signal, represents that signal.	plugins/shell/guest-js/index.ts:562

Type Aliases

IOPayload

type IOPayload =
  | string
  | Uint8Array;

Defined in: plugins/shell/guest-js/index.ts:566

Event payload type

Functions

open()

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

Defined in: plugins/shell/guest-js/index.ts:601

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