shell
@tauri-apps/api / shell
Module: 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 tauri.conf.json > build > withGlobalTauri
is set to true.
The APIs must be allowlisted on 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 ^https?://
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​
Interfaces​
Functions​
open​
â–¸ open(path
, openWith?
): 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');
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 ^https?:// . |
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
>