shell

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

This package is also accessible with window.__TAURI__.shell when build.withGlobalTauri in tauri.conf.json is set to true.

The APIs must be added to tauri.allowlist.shell in tauri.conf.json:

{
  "tauri": {
    "allowlist": {
      "shell": {
        "all": true, // enable all shell APIs
        "execute": true, // enable process spawn APIs
        "sidecar": true, // enable spawning sidecars
        "open": true // enable opening files/URLs using the default program
      }
    }
  }
}

It is recommended to allowlist only the APIs you use for optimal bundle size and security.

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 allowlist, 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 shell allowlist 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 constructor. If it's a sidecar, this must be the value defined on tauri.conf.json > tauri > 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"

Configuration:

{
  "scope": [
    {
      "name": "run-git-commit",
      "cmd": "git",
      "args": ["commit", "-m", { "validator": "\\S+" }]
    }
  ]
}

Usage:

import { Command } from '@tauri-apps/api/shell'
new Command('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`

Since: 1.1.0

Constructors

`constructor`

new Child(pid: number): Child

Parameters

Name	Type
`pid`	`number`

Defined in: shell.ts:325

Properties

`pid`

pid: number

The child process pid.

Defined in: shell.ts:323

Methods

`kill`

kill(): Promise<void>

Kills the child process.

Returns: Promise<void>

A promise indicating the success or failure of the operation.

`write`

write(data: string | Uint8Array): Promise<void>

Writes data to the stdin.

Example

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

Parameters

Name	Type	Description
`data`	`string` \| `Uint8Array`	The message to write, either a string or a byte array.

Returns: Promise<void>

A promise indicating the success or failure of the operation.

`Command`

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

Example

import { Command } from '@tauri-apps/api/shell';
const command = new Command('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: 1.1.0

Hierarchy

EventEmitter<"close" | "error">
- Command

Constructors

`constructor`

new Command(program: string, args?: string | string[], options?: SpawnOptions): Command

Creates a new Command instance.

Parameters

Name	Type	Default value	Description
`program`	`string`	`undefined`	The program name to execute. It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
`args`	`string` \| `string`[]	`[]`	Program arguments.
`options?`	`SpawnOptions`	`undefined`	Spawn options.

Overrides: EventEmitter.constructor

Defined in: shell.ts:413

Properties

`stderr`

Readonly stderr: EventEmitter<"data">

Event emitter for the stderr. Emits the data event.

Defined in: shell.ts:403

`stdout`

Readonly stdout: EventEmitter<"data">

Event emitter for the stdout. Emits the data event.

Defined in: shell.ts:401

Methods

`addListener`

addListener(eventName: "error" | "close", listener: fn): Command

Alias for emitter.on(eventName, listener).

Since: 1.1.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`
`listener`	(...`args`: `any`[]) => `void`

Returns: Command

`execute`

execute(): Promise<ChildProcess>

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

Example

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

Returns: Promise<ChildProcess>

A promise resolving to the child process output.

`listenerCount`

listenerCount(eventName: "error" | "close"): number

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

Since: 1.1.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`

Returns: number

`off`

off(eventName: "error" | "close", listener: fn): Command

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.

Since: 1.1.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`
`listener`	(...`args`: `any`[]) => `void`

Returns: Command

`on`

on(eventName: "error" | "close", listener: fn): Command

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.

Since: 1.0.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`
`listener`	(...`args`: `any`[]) => `void`

Returns: Command

`once`

once(eventName: "error" | "close", listener: fn): Command

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.

Since: 1.1.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`
`listener`	(...`args`: `any`[]) => `void`

Returns: Command

`prependListener`

prependListener(eventName: "error" | "close", listener: fn): Command

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.

Since: 1.1.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`
`listener`	(...`args`: `any`[]) => `void`

Returns: Command

`prependOnceListener`

prependOnceListener(eventName: "error" | "close", listener: fn): Command

Adds a one-timelistener function for the event named eventName to thebeginning 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.

Since: 1.1.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`
`listener`	(...`args`: `any`[]) => `void`

Returns: Command

`removeAllListeners`

removeAllListeners(event?: "error" | "close"): Command

Removes all listeners, or those of the specified eventName.

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

Since: 1.1.0

Parameters

Name	Type
`event?`	`"error"` \| `"close"`

Returns: Command

`removeListener`

removeListener(eventName: "error" | "close", listener: fn): Command

Alias for emitter.off(eventName, listener).

Since: 1.1.0

Parameters

Name	Type
`eventName`	`"error"` \| `"close"`
`listener`	(...`args`: `any`[]) => `void`

Returns: Command

`spawn`

spawn(): Promise<Child>

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

Returns: Promise<Child>

A promise resolving to the child process handle.

`sidecar`

Static sidecar(program: string, args?: string | string[], options?: SpawnOptions): Command

Creates a command to execute the given sidecar program.

Example

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

Parameters

Name	Type	Default value	Description
`program`	`string`	`undefined`	The program to execute. It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
`args`	`string` \| `string`[]	`[]`	-
`options?`	`SpawnOptions`	`undefined`	-

Returns: Command

`EventEmitter<E>`

Since: 1.0.0

Type parameters

E extends string

Hierarchy

EventEmitter
- Command

Constructors

`constructor`

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

Type parameters

E extends string

Methods

`addListener`

addListener(eventName: E, listener: fn): EventEmitter<E>

Alias for emitter.on(eventName, listener).

Since: 1.1.0

Parameters

Name	Type
`eventName`	`E`
`listener`	(...`args`: `any`[]) => `void`

Returns: EventEmitter<E>

`listenerCount`

listenerCount(eventName: E): number

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

Since: 1.1.0

Parameters

Name	Type
`eventName`	`E`

Returns: number

`off`

off(eventName: E, listener: fn): EventEmitter<E>

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.

Since: 1.1.0

Parameters

Name	Type
`eventName`	`E`
`listener`	(...`args`: `any`[]) => `void`

Returns: EventEmitter<E>

`on`

on(eventName: E, listener: fn): EventEmitter<E>

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

Since: 1.0.0

Parameters

Name	Type
`eventName`	`E`
`listener`	(...`args`: `any`[]) => `void`

Returns: EventEmitter<E>

`once`

once(eventName: E, listener: fn): EventEmitter<E>

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.

Since: 1.1.0

Parameters

Name	Type
`eventName`	`E`
`listener`	(...`args`: `any`[]) => `void`

Returns: EventEmitter<E>

`prependListener`

prependListener(eventName: E, listener: fn): EventEmitter<E>

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

Since: 1.1.0

Parameters

Name	Type
`eventName`	`E`
`listener`	(...`args`: `any`[]) => `void`

Returns: EventEmitter<E>

`prependOnceListener`

prependOnceListener(eventName: E, listener: fn): EventEmitter<E>

Adds a one-timelistener function for the event named eventName to thebeginning 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.

Since: 1.1.0

Parameters

Name	Type
`eventName`	`E`
`listener`	(...`args`: `any`[]) => `void`

Returns: EventEmitter<E>

`removeAllListeners`

removeAllListeners(event?: E): EventEmitter<E>

Removes all listeners, or those of the specified eventName.

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

Since: 1.1.0

Parameters

Name	Type
`event?`	`E`

Returns: EventEmitter<E>

`removeListener`

removeListener(eventName: E, listener: fn): EventEmitter<E>

Alias for emitter.off(eventName, listener).

Since: 1.1.0

Parameters

Name	Type
`eventName`	`E`
`listener`	(...`args`: `any`[]) => `void`

Returns: EventEmitter<E>

Interfaces

`ChildProcess`

Since: 1.0.0

Properties

`code`

code: null | number

Exit code of the process. null if the process was terminated by a signal on Unix.

Defined in: shell.ts:109

`signal`

signal: null | number

If the process was terminated by a signal, represents that signal.

Defined in: shell.ts:111

`stderr`

stderr: string

The data that the process wrote to stderr.

Defined in: shell.ts:115

`stdout`

stdout: string

The data that the process wrote to stdout.

Defined in: shell.ts:113

`SpawnOptions`

Since: 1.0.0

Properties

`cwd`

Optional cwd: string

Current working directory.

Defined in: shell.ts:88

`encoding`

Optional encoding: string

Character encoding for stdout/stderr

Since: 1.1.0

Defined in: shell.ts:96

`env`

Optional env: Record<string, string>

Environment variables. set to null to clear the process env.

Defined in: shell.ts:90

Functions

`open`

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

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.

Example

import { open } from '@tauri-apps/api/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: 1.0.0

Parameters

Name	Type	Description
`path`	`string`	The path or URL to open. This value is matched against the string regex defined on `tauri.conf.json > tauri > allowlist > shell > open`, which defaults to `^((mailto:\w+)\\|(tel:\w+)\\|(https?://\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>

shell

Security​

Restricting access to the open API​

Restricting access to the Command APIs​

Example scope configuration​

Classes​

Child​

Constructors​

constructor​

Properties​

pid​

Methods​

kill​

write​

Command​

Constructors​

constructor​

Properties​

stderr​

stdout​

Methods​

addListener​

execute​

listenerCount​

off​

on​

once​

prependListener​

prependOnceListener​

removeAllListeners​

removeListener​

spawn​

sidecar​

EventEmitter<E>​

Constructors​

constructor​

Methods​

addListener​

listenerCount​

off​

on​

once​

prependListener​

prependOnceListener​

removeAllListeners​

removeListener​

Interfaces​

ChildProcess​

Properties​

code​

signal​

stderr​

stdout​

SpawnOptions​

Properties​

cwd​

encoding​

env​

Functions​

open​

Security

Restricting access to the `open` API

Restricting access to the `Command` APIs

Example scope configuration

Classes

`Child`

Constructors

`constructor`

Properties

`pid`

Methods

`kill`

`write`

`Command`

Constructors

`constructor`

Properties

`stderr`

`stdout`

Methods

`addListener`

`execute`

`listenerCount`

`off`

`on`

`once`

`prependListener`

`prependOnceListener`

`removeAllListeners`

`removeListener`

`spawn`

`sidecar`

`EventEmitter<E>`

Constructors

`constructor`

Methods

`addListener`

`listenerCount`

`off`

`on`

`once`

`prependListener`

`prependOnceListener`

`removeAllListeners`

`removeListener`

Interfaces

`ChildProcess`

Properties

`code`

`signal`

`stderr`

`stdout`

`SpawnOptions`

Properties

`cwd`

`encoding`

`env`

Functions

`open`