Shell API

The Shell API gives a Tauri app the ability to reach past the webview and interact with the user's operating system. It handles two distinct jobs: opening a resource with the default program (a URL in a browser, a PDF in a PDF reader) and running a command-line program as a child process, with full access to its input and output.

In Tauri v2, the shell functionality ships as a plugin. You opt into it by adding both the Rust crate and the JavaScript package to your project. Nothing is available unless you intentionally register it. The Introduction covers that install in isolation.

Installing the Shell Plugin

Before any shell function can be called, the plugin must be wired up on both the Rust side and the JavaScript side. The steps are short, and the process is the same as any other Tauri v2 plugin.

[dependencies]
tauri-plugin-shell = "2"

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_shell::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

npm install @tauri-apps/plugin-shell

Opening External Resources

An external resource is anything the operating system knows how to handle that sits outside your application window: a website, a local file, a directory, or even a mailto: link. The open function asks the OS to launch the default program for that path or URL.

import { open } from '@tauri-apps/plugin-shell';
// Open a website in the default browser
await open('https://tauri.app');
// Open a local file with its associated app
await open('/Users/alex/documents/report.pdf');
// Open a folder in the system file explorer
await open('/Users/alex/projects');

The call returns a promise. If the OS cannot find a program to handle the resource, the promise rejects. There is no return value on success — the external program takes over and your app continues running independently.

The open function in a React component

This example renders a text input and a button. A user can type a URL or file path and open it with one click.

import { useState } from 'react';
import { open } from '@tauri-apps/plugin-shell';
function App() {
  const [path, setPath] = useState('https://tauri.app');
  const handleOpen = async () => {
    if (!path.trim()) return;
    try {
      await open(path);
    } catch (error) {
      console.error('Failed to open resource:', error);
    }
  };
  return (
    <div>
      <input
        type="text"
        value={path}
        onChange={(e) => setPath(e.target.value)}
        placeholder="URL or file path"
      />
      <button onClick={handleOpen}>Open</button>
    </div>
  );
}
export default App;

The code imports open directly from the shell plugin. No additional Rust code is required beyond the plugin registration shown earlier. However, for open to actually work, the capability file must permit it — a blank configuration will block every shell call, including open.

Spawning Child Processes

Opening a resource is a fire-and-forget action. Running a command is a conversation: you launch a process, optionally write to its stdin, and read its stdout and stderr. Tauri exposes this through the Command class. For restarting or exiting the app itself, use the Process plugin rather than shell.

The two primary methods are execute and spawn. execute runs the process to completion and returns all output at once. spawn returns a handle while the process is still running, and you listen to events for each chunk of output.

Running a command and collecting output

import { Command } from '@tauri-apps/plugin-shell';
const output = await Command.create('echo', ['hello from tauri']).execute();
console.log(output.stdout); // "hello from tauri\n"
console.log(output.code);   // 0

Command.create takes the program name as the first argument and an array of arguments as the second. It mirrors how you would type a command in a terminal. The returned ChildProcess object contains stdout, stderr, code, and signal.

This is ideal for short-lived utilities: git status, node --version, ffmpeg -i input.mp4 -f null -. The promise resolves only when the process exits, so a stuck process will hang the call.

Spawning a long-running process

When a command produces output gradually — a build script, a server, a file conversion — spawn lets you handle output as it arrives. You register event listeners on the command's stdout and stderr emitters before calling spawn.

import { Command } from '@tauri-apps/plugin-shell';
const cmd = Command.create('ping', ['-c', '4', 'tauri.app']);
cmd.stdout.on('data', (line) => {
  console.log('stdout:', line);
});
cmd.stderr.on('data', (line) => {
  console.error('stderr:', line);
});
cmd.on('close', (payload) => {
  console.log(`Process exited with code ${payload.code}`);
});
cmd.on('error', (error) => {
  console.error('Failed to start process:', error);
});
const child = await cmd.spawn();
console.log('Spawned PID:', child.pid);

The child handle returned by spawn gives you the process ID and two methods: write to send data to stdin, and kill to terminate the process.

// Write to the process's stdin
await child.write('some input\n');
// Forcefully stop the process
await child.kill();

The event-based API is the same pattern Node.js developers know from child_process.spawn. A key difference: Tauri does not pipe stdin/stdout through the webview's JavaScript event loop as a raw stream; each line of output triggers a data event as a string.

Streaming output in a React component

A practical example: a text area where the user enters a command, and the output streams into a scrollable log below.

import { useState, useRef } from 'react';
import { Command } from '@tauri-apps/plugin-shell';
function App() {
  const [command, setCommand] = useState('echo Hello');
  const [output, setOutput] = useState('');
  const outputRef = useRef('');
  const handleRun = async () => {
    setOutput('');
    outputRef.current = '';
    const [program, ...args] = command.split(' ');
    const cmd = Command.create(program, args);
    cmd.stdout.on('data', (line) => {
      outputRef.current += line;
      setOutput(outputRef.current);
    });
    cmd.stderr.on('data', (line) => {
      outputRef.current += `[stderr] ${line}`;
      setOutput(outputRef.current);
    });
    cmd.on('close', (payload) => {
      outputRef.current += `\n--- exit code: ${payload.code} ---`;
      setOutput(outputRef.current);
    });
    cmd.on('error', (err) => {
      outputRef.current += `\nError: ${err}`;
      setOutput(outputRef.current);
    });
    await cmd.spawn();
  };
  return (
    <div>
      <input
        type="text"
        value={command}
        onChange={(e) => setCommand(e.target.value)}
        placeholder="e.g., echo Hello"
      />
      <button onClick={handleRun}>Run</button>
      <pre style={{ whiteSpace: 'pre-wrap', background: '#1e1e1e', color: '#ddd', padding: '1rem' }}>
        {output}
      </pre>
    </div>
  );
}
export default App;

The component splits the command string on spaces to separate the program name from arguments. This is fine for a demo, but a real app should handle quoted strings and escaped characters. The <pre> block preserves newlines so the streaming output appears line by line just as it would in a terminal.

Security Configuration

The Shell API can do irreversible things: delete files, send network requests, install software. Tauri v2 locks it down with a two-layer permission system: capabilities declare which shell operations are allowed, and scopes restrict which specific programs and arguments can be used. The dedicated Security Considerations page goes deeper on injection risks.

Capabilities

Every permission a Tauri app needs is granted in a capability file, typically src-tauri/capabilities/default.json. The shell plugin recognizes three permission identifiers:

An app that only needs to open URLs does not need shell:allow-execute or shell:allow-spawn. Each permission is a separate gate.

{
  "identifier": "default",
  "description": "Default capabilities for the app",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "shell:allow-open"
  ]
}

This configuration allows open but blocks every form of command execution. The reverse — allowing execute but not open — is equally possible.

Command scopes

Granting shell:allow-execute without a scope means any program name can be passed to Command.create, which is equivalent to giving the frontend a full shell. The scope array restricts this to an explicit list of programs.

A scope entry is an object inside the capability file's shell permission. Each entry maps a name (used in JavaScript) to a real binary path and defines what arguments are allowed.

{
  "identifier": "default",
  "description": "Default capabilities for the app",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "shell:allow-execute",
    "shell:allow-spawn",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "name": "run-git-commit",
          "cmd": "git",
          "args": [
            "commit",
            "-m",
            { "validator": "\\S+" }
          ]
        }
      ]
    }
  ]
}

Now the JavaScript side can only create Command.create('run-git-commit', ['commit', '-m', 'fix typo']). Passing 'git' directly will be rejected because 'git' is not a scope name — 'run-git-commit' is. The args array specifies that exactly three arguments are required: the literal string "commit", the literal string "-m", and a non-whitespace string validated by the regex \S+.

Open scope

The open function can also be scoped. By default, granting shell:allow-open permits any URL or path. To restrict it to specific domains or schemes, attach a scope with a regex pattern.

{
  "identifier": "default",
  "description": "Default capabilities for the app",
  "windows": ["main"],
  "permissions": [
    "core:default",
    {
      "identifier": "shell:allow-open",
      "allow": [
        { "validator": "^https://tauri\\.app/" }
      ]
    }
  ]
}

With this configuration, open('https://tauri.app/docs') works, but open('https://github.com') is rejected. The regex runs against the entire string passed to open.

Practical permission strategy

A thoughtful capability file is the single most impactful security decision in a Tauri app that uses shell. The principle is to grant the minimum surface area the feature actually needs.

• If the app only opens a specific documentation URL, scope open to that exact prefix.
• If the app runs a CLI tool, create a dedicated scope entry that fixes the argument structure. Never allow args: true unless the arguments are fully trusted and non-user-supplied.
• Avoid shell:allow-execute with an empty or [{ "name": "*", "cmd": "*" }] scope outside of development. This gives the frontend the same access as the user running the app.

Common Mistakes and Troubleshooting

Shell API issues often surface as silent failures or console errors. The root cause is almost always a mismatch between the capability file and the JavaScript call.

Using the OS binary name instead of the scope name. Command.create('git', ...) fails when the scope entry is named 'run-git'. The first argument to create must match the name field in the scope, not the cmd field.

Forgetting to add the permission to the capability file. A fresh install of the plugin with no changes to capabilities/default.json will block every shell call. The open call will hang or throw a permission denied error. Check the console output during tauri dev for lines like permission not granted.

Expecting shell syntax to work. Redirections (>), pipes (|), environment variable expansion ($HOME), and glob patterns (*.txt) are features of a shell, not the operating system's process spawn API. They do not work in Command.create unless the command itself is a shell: Command.create('bash', ['-c', 'ls *.txt > out.txt']).

Scope regex too restrictive. The validator regex must match the entire argument string, not a substring. The pattern \\S+ matches one word; .* matches anything; \\d+ matches a number. A regex that does not match the argument the user typed will cause the command to fail before the process even starts.

The Shell API is the bridge between a Tauri app's web frontend and the full power of the host operating system. Used with the correct scoping, it opens external resources and runs trusted utilities safely. A capability file that precisely defines what can be opened and executed turns the shell plugin from a broad backdoor into a controlled, auditable surface.