Interfaz de Línea de Comandos (CLI)

GitHubnpmcrates.io

Referencia de API

Tauri permite que tu aplicación tenga una CLI mediante clap, un analizador de argumentos de línea de comandos robusto. Con una definición simple de CLI en tu archivo tauri.conf.json, puedes definir tu interfaz y leer su mapa de coincidencias de argumentos en JavaScript y/o Rust.

Plataformas Soportadas

Este plugin requiere una versión de Rust de al menos 1.77.2

Plataforma	Nivel	Notas
windows
linux
macos
android
ios

• Windows
  • Debido a una limitación del SO, las aplicaciones de producción no pueden escribir texto de vuelta a la consola que las llama de forma predeterminada. Consulta tauri#8305 para ver una solución alternativa.

Configuración

Instala el plugin CLI para comenzar.

Automático

Usa el gestor de paquetes de tu proyecto para agregar la dependencia:

npm

npm run tauri add cli

yarn

yarn run tauri add cli

pnpm

pnpm tauri add cli

deno

deno task tauri add cli

bun

bun tauri add cli

cargo

cargo tauri add cli

Manual

1. Ejecuta el siguiente comando en la carpeta src-tauri para agregar el plugin a las dependencias del proyecto en Cargo.toml:

   cargo add tauri-plugin-cli --target 'cfg(any(target_os = "macos", windows, target_os = "linux"))'

   2. Modifica lib.rs para inicializar el plugin:

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .setup(|app| {
               #[cfg(desktop)]
               app.handle().plugin(tauri_plugin_cli::init());
               Ok(())
           })
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

   3. Instala los bindings de JavaScript utilizando tu gestor de paquetes de JavaScript preferido:
   npm

   npm install @tauri-apps/plugin-cli

   yarn

   yarn add @tauri-apps/plugin-cli

   pnpm

   pnpm add @tauri-apps/plugin-cli

   deno

   deno add npm:@tauri-apps/plugin-cli

   bun

   bun add @tauri-apps/plugin-cli

Configuración Base

Bajo tauri.conf.json, tienes la siguiente estructura para configurar la interfaz:

src-tauri/tauri.conf.json

{
  "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"
            }
          ]
        }
      }
    }
  }
}

Nota

Todas las configuraciones JSON aquí son solo muestras; muchos otros campos se han omitido en aras de la claridad.

Agregar Argumentos

El arreglo args representa la lista de argumentos aceptados por su comando o subcomando.

Argumentos Posicionales

Un argumento posicional se identifica por su posición en la lista de argumentos. Con la siguiente configuración:

src-tauri/tauri.conf.json

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

Los usuarios pueden ejecutar tu aplicación como ./app tauri.txt dest.txt y el mapa de coincidencias de args definirá source como "tauri.txt" y destination como "dest.txt".

Argumentos con Nombre

Un argumento con nombre es un par (clave, valor) donde la clave identifica al valor. Con la siguiente configuración:

tauri-src/tauri.conf.json

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

Los usuarios pueden ejecutar tu aplicación como ./app --type foo bar, ./app -t foo -t bar o ./app --type=foo,bar y el mapa de coincidencias de args definirá type como ["foo", "bar"].

Argumentos de Flag (Indicador)

Un argumento de flag es una clave independiente cuya presencia o ausencia proporciona información a tu aplicación. Con la siguiente configuración:

tauri-src/tauri.conf.json

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

Los usuarios pueden ejecutar tu aplicación como ./app -v -v -v, ./app --verbose --verbose --verbose o ./app -vvv y el mapa de coincidencias de args definirá verbose como true, con occurrences = 3.

Subcomandos

Algunas aplicaciones CLI tienen interfaces adicionales como subcomandos. Por ejemplo, la CLI de git tiene git branch, git commit y git push. Puedes definir interfaces anidadas adicionales con el arreglo subcommands:

tauri-src/tauri.conf.json

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

Su configuración es la misma que la configuración de la aplicación raíz, con description, longDescription, args, etc.

Uso

El plugin CLI está disponible tanto en JavaScript como en Rust.

JavaScript

import { getMatches } from '@tauri-apps/plugin-cli';
// when using `"withGlobalTauri": true`, you may use
// const { getMatches } = window.__TAURI__.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
  }
}

Rust

src-tauri/src/lib.rs

use tauri_plugin_cli::CliExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub 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");
}

Permisos

De forma predeterminada, todos los comandos y alcances (scopes) potencialmente peligrosos del plugin están bloqueados y no se puede acceder a ellos. Debes modificar los permisos en tu configuración de capabilities para habilitarlos.

Consulta la Visión General de Capacidades para obtener más información y la guía paso a paso para usar permisos de plugins.

src-tauri/capabilities/default.json

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

Permiso Predeterminado

Permite leer las coincidencias (matches) de la CLI

Este conjunto de permisos predeterminado incluye lo siguiente:

• allow-cli-matches

Tabla de Permisos

Identificador	Descripción
cli:allow-cli-matches	Habilita el comando cli_matches sin ningún alcance preconfigurado.
cli:deny-cli-matches	Deniega el comando cli_matches sin ningún alcance preconfigurado.