tauri/docs/usage/guides/cli.md

title
Make your own CLI

import Alert from '@theme/Alert'

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.

Base Configuration

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

{
  "tauri": {
    "cli": {
      "description": "", // command description that's shown on help
      "longDescription": "", // command long description that's shown on help
      "beforeHelp": "", // content to show before the help text
      "afterHelp": "", // content to show after the help text
      "args": [], // list of arguments of the command, we'll explain it later
      "subcommands": {
        "subcommand-name": {
          // configures a subcommand that is accessible
          // with `$ ./app subcommand-name --arg1 --arg2 --etc`
          // configuration as above, with "description", "args", etc.
        }
      }
    }
  }
}

All JSON configurations here are just samples, many other fields have been omitted for the sake of clarity.

Adding Arguments

The args array represents the list of arguments accepted by its command or subcommand. You can find more details about the way to configure them here.

Positional Arguments

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

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

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".

Named Arguments

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"].

Flag Arguments

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",
    "multipleOccurrences": true
  ]
}

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.

Subcommands

Some CLI applications has 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.

Reading the matches

Rust

use tauri::api::cli::get_matches;

fn main() {
  let context = tauri::generate_context!();
  let cli_config = context.config().tauri.cli.clone().unwrap();
  
  match get_matches(&cli_config) {
    // `matches` here is a Struct with { args, subcommand }.
    // `args` is `HashMap<String, ArgData>` where `ArgData` is a struct with { value, occurances }.
    // `subcommand` is `Option<Box<SubcommandMatches>>` where `SubcommandMatches` is a struct with { name, matches }.
    Ok(matches) => {
      println!("{:?}", matches)
    }
    Err(_) => {}
  };
  
  tauri::Builder::default()
  .run(context)
  .expect("error while running tauri application");
}

JavaScript

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

getMatches().then((matches) => {
  // do something with the { args, subcommand } matches
})

Complete documentation

You can find more about the CLI configuration here.