Command Line Interface (CLI)

API Reference

Tauri enables your app to have a CLI through clap, a robust command line argument parser. With a simple CLI definition in your tauri.conf.json file, you can define your interface and read its argument matches map on JavaScript and/or Rust.

Windows
Linux
macOS

This plugin requires a Rust version of at least 1.75

Install the CLI plugin to get started.

Automatic
Manual

Use your project’s package manager to add the dependency:

npm run tauri add cli

yarn run tauri add cli

pnpm tauri add cli

cargo tauri add cli

Install the Core plugin by adding the following to your Cargo.toml file:

# you can add the dependencies on the `[dependencies]` section if you do not target mobile
[target."cfg(not(any(target_os = \"android\", target_os = \"ios\")))".dependencies]
tauri-plugin-cli = "2.0.0-beta"
# alternatively with Git:
tauri-plugin-cli = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }

Modify lib.rs to initialize the plugin:

#[cfg_attr(mobile, tauri::mobile_entry_point)]
fn run() {
  tauri::Builder::default()
    .plugin(tauri_plugin_cli::init())
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

Install the JavaScript Guest bindings using your preferred JavaScript package manager:

npm install @tauri-apps/plugin-cli

yarn add @tauri-apps/plugin-cli

pnpm add @tauri-apps/plugin-cli

Under tauri.conf.json, you have the following structure to configure the interface:

{
  "plugins": {
    "cli": {
      "description": "Tauri CLI Plugin Example",
      "args": [
        {
          "short": "v",
          "name": "verbose",
          "description": "Verbosity level"
        }
      ],
      "subcommands": {
        "run": {
          "description": "Run the application",
          "args": [
            {
              "name": "debug",
              "description": "Run application in debug mode"
            },
            {
              "name": "release",
              "description": "Run application in release mode"
            }
          ]
        }
      }
    }
  }
}

The args array represents the list of arguments accepted by its command or subcommand.

A positional argument is identified by its position in the list of arguments. With the following configuration:

{
  "args": [
    {
      "name": "source",
      "index": 1,
      "takesValue": true
    },
    {
      "name": "destination",
      "index": 2,
      "takesValue": true
    }
  ]
}

Users can run your app as ./app tauri.txt dest.txt and the arg matches map will define source as "tauri.txt" and destination as "dest.txt".

A named argument is a (key, value) pair where the key identifies the value. With the following configuration:

{
  "args": [
    {
      "name": "type",
      "short": "t",
      "takesValue": true,
      "multiple": true,
      "possibleValues": ["foo", "bar"]
    }
  ]
}

Users can run your app as ./app --type foo bar, ./app -t foo -t bar or ./app --type=foo,bar and the arg matches map will define type as ["foo", "bar"].

A flag argument is a standalone key whose presence or absence provides information to your application. With the following configuration:

{
  "args": [
    {
      "name": "verbose",
      "short": "v"
    }
  ]
}

Users can run your app as ./app -v -v -v, ./app --verbose --verbose --verbose or ./app -vvv and the arg matches map will define verbose as true, with occurrences = 3.

Some CLI applications have additional interfaces as subcommands. For instance, the git CLI has git branch, git commit and git push. You can define additional nested interfaces with the subcommands array:

{
  "cli": {
    ...
    "subcommands": {
      "branch": {
        "args": []
      },
      "push": {
        "args": []
      }
    }
  }
}

Its configuration is the same as the root application configuration, with the description, longDescription, args, etc.

The CLI plugin is available in both JavaScript and Rust.

JavaScript
Rust

import { getMatches } from '@tauri-apps/plugin-cli';

const matches = await getMatches();
if (matches.subcommand?.name === 'run') {
  // `./your-app run $ARGS` was executed
  const args = matches.subcommand.matches.args;
  if (args.debug?.value === true) {
    // `./your-app run --debug` was executed
  }
  if (args.release?.value === true) {
    // `./your-app run --release` was executed
  }
}

use tauri_plugin_cli::CliExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
fn run() {
   tauri::Builder::default()
       .plugin(tauri_plugin_cli::init())
       .setup(|app| {
           match app.cli().matches() {
               // `matches` here is a Struct with { args, subcommand }.
               // `args` is `HashMap<String, ArgData>` where `ArgData` is a struct with { value, occurrences }.
               // `subcommand` is `Option<Box<SubcommandMatches>>` where `SubcommandMatches` is a struct with { name, matches }.
               Ok(matches) => {
                   println!("{:?}", matches)
               }
               Err(_) => {}
           }
           Ok(())
       })
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
}

By default all plugin commands are blocked and cannot be accessed. You must define a list of permissions in your capabilities configuration.

See Access Control List for more information.

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": ["cli:default"]
}

Permission	Description
`cli:default`	Allows reading the CLI matches.
`cli:allow-cli-matches`	Enables the cli_matches command without any pre-configured scope.
`cli:deny-cli-matches`	Denies the cli_matches command without any pre-configured scope.