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 ontauri.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 eventName
and 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 eventName
and 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
​
Executes the command as a child process, returning a handle to it.
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
extendsstring
Hierarchy
- EventEmitter
Constructors​
constructor
​
new EventEmitter<
E
>():EventEmitter
<E
>
Type parameters
E
extendsstring
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
>
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 eventName
and 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 | 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
>
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 eventName
and 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 | 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
>