--- title: influxdb3 create trigger description: The influxdb3 create trigger command creates a new trigger for the processing engine. url: https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/create/trigger/ estimated_tokens: 4921 product: InfluxDB 3 Enterprise version: enterprise publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/create/trigger/ date: '2026-07-11T10:53:18+00:00' lastmod: '2026-07-11T10:53:18+00:00' --- The `influxdb3 create trigger` command creates a new trigger for the processing engine. ## Usage ```bash # Syntax influxdb3 create trigger [OPTIONS] \ --database \ --token \ --plugin-filename \ --trigger-spec \ ``` ## Arguments * **TRIGGER\_NAME**: A name for the new trigger. ## Options |Option| | Description | |------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-H` | `--host` | Host URL of the running InfluxDB 3 Enterprise server (default is `http://127.0.0.1:8181`) | | `-d` | `--database` | *(Required)* Name of the database to operate on | | | `--token` | *(Required)* Authentication token | | `-p` | `--path` |Path to plugin file or directory (single `.py` file or directory containing `__init__.py` for multifile plugins). Can be local path (with `--upload`) or server path. Replaces `--plugin-filename`.| | | `--upload` | Upload local plugin files to the server. Requires admin token. Use with `--path` to specify local files. | | | `--plugin-filename` | *(Deprecated: use `--path` instead)* Name of the file, stored in the server’s `plugin-dir`, that contains the Python plugin code to run | | | `--trigger-spec` | Trigger specification: `table:`, `all_tables`, `every:`, `cron:`, or `request:` | | |`--trigger-arguments`| Additional arguments for the trigger, in the format `key=value`, separated by commas (for example, `arg1=val1,arg2=val2`) | | | `--disabled` | Create the trigger in disabled state (default: enabled) | | | `--error-behavior` | Error handling behavior: `log`, `retry`, or `disable` (default: `log`) | | |`--run-asynchronous` | Run the trigger asynchronously, allowing multiple triggers to run simultaneously (default is synchronous) | | | `--tls-ca` | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | `--tls-no-verify` | Disable TLS certificate verification (**Not recommended in production**, useful for self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | Additional InfluxDB 3 Enterprise option: |Option| | Description | |------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | |`--node-spec`|Which process nodes’ schedulers own the trigger. Two value formats are supported: `all` (default) - every process node (a node with `--plugin-dir` configured) owns the trigger and schedules it independently, or `nodes:[,..]` - only the schedulers on the listed nodes own the trigger| ### Reference a plugin from GitHub To fetch a plugin remotely instead of downloading it locally, prefix the plugin path with `gh:`. The path after the prefix is appended to the configured `--plugin-repo`–for example: ``` gh:examples/wal_plugin/wal_plugin.py ``` Despite the name, `gh:` doesn’t require GitHub or a Git repository–`--plugin-repo` accepts any HTTP/HTTPS URL that serves raw plugin files. By default, `gh:`-prefixed plugins resolve against the [`influxdata/influxdb3_plugins`](https://github.com/influxdata/influxdb3_plugins) repository at `https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/`. For example, `gh:examples/wal_plugin/wal_plugin.py` resolves to `https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/examples/wal_plugin/wal_plugin.py`. To reference plugins from a different repository, set the `--plugin-repo` server option (or the `INFLUXDB3_PLUGIN_REPO` environment variable) to a raw content URL base path. For more information, see the [`plugin-repo` config option](/influxdb3/enterprise/reference/config-options/#plugin-repo). InfluxDB fetches the plugin over HTTP when the trigger is created (to validate it), and again each time the trigger starts–for example, on server startup or when re-enabled. If the fetch fails, `influxdb3 create trigger` returns an error with the HTTP status code and URL: ``` error fetching plugin from repository: 404 Not Found https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/not_found.py ``` Unlike local plugins, `gh:`-prefixed plugins aren’t automatically reloaded when the source changes–disable and re-enable the trigger to fetch updates. Only single-file plugins are supported with the `gh:` prefix; multi-file plugin directories must be uploaded locally with `--upload`. ### Option environment variables You can use the following environment variables to set command options: | Environment Variable | Option | |-------------------------|-----------------| | `INFLUXDB3_HOST_URL` | `--host` | |`INFLUXDB3_DATABASE_NAME`| `--database` | | `INFLUXDB3_AUTH_TOKEN` | `--token` | |`INFLUXDB3_TLS_NO_VERIFY`|`--tls-no-verify`| ## Examples The following examples show how to use the `influxdb3 create trigger` command to create triggers in different scenarios. * [Create a trigger for a specific table](#create-a-trigger-for-a-specific-table) * [Create a trigger for all tables](#create-a-trigger-for-all-tables) * [Create a trigger with a schedule](#create-a-trigger-with-a-schedule) * [Create a trigger for HTTP requests](#create-a-trigger-for-http-requests) * [Create a trigger with a multifile plugin](#create-a-trigger-with-a-multifile-plugin) * [Upload and create a trigger with a local plugin](#upload-and-create-a-trigger-with-a-local-plugin) * [Create a trigger with additional arguments](#create-a-trigger-with-additional-arguments) * [Create a disabled trigger](#create-a-disabled-trigger) * [Create a trigger with error handling](#create-a-trigger-with-error-handling) Replace the following placeholders with your values: * `DATABASE_NAME`: Database name * `AUTH_TOKEN`: Authentication token * `PLUGIN_FILENAME`: Python plugin filename * `TRIGGER_NAME`: Name of the trigger to create * `TABLE_NAME`: Name of the table to trigger on ### Create a trigger for a specific table Create a trigger that processes data from a specific table. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename PLUGIN_FILENAME \ --trigger-spec table:TABLE_NAME \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [data write plugin](/influxdb3/enterprise/plugins/#create-a-data-write-plugin) interface. ### Create a trigger for all tables Create a trigger that applies to all tables in the specified database. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec all_tables \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [data write plugin](/influxdb3/enterprise/plugins/#create-a-data-write-plugin) interface. This is useful when you want a trigger to apply to any table in the database, regardless of name. ### Create a trigger with a schedule Create a trigger that runs at a specific interval using a duration. Supported duration units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months), `y` (years). Maximum interval is 1 year. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec every:5m \ TRIGGER_NAME ``` Create a trigger that runs based on a cron schedule using extended 6-field cron format. The cron expression follows the format: ``` second minute hour day_of_month month day_of_week ``` Fields: * **second**: 0-59 * **minute**: 0-59 * **hour**: 0-23 * **day\_of\_month**: 1-31 * **month**: 1-12 or JAN-DEC * **day\_of\_week**: 0-7 (0 or 7 is Sunday) or SUN-SAT Example: Run at 6:00 AM every weekday (Monday-Friday): ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec "cron:0 0 6 * * 1-5" \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [scheduled plugin](/influxdb3/enterprise/plugins/#create-a-scheduled-plugin) interface. ### Create a trigger for HTTP requests Create a trigger that provides an API endpoint and processes HTTP requests. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename PLUGIN_FILENAME \ --trigger-spec request:REQUEST_PATH \ TRIGGER_NAME ``` `PLUGIN_FILENAME` must implement the [HTTP request plugin](/influxdb3/enterprise/plugins/#create-an-http-request-plugin) interface. ### Create a trigger with a multifile plugin Create a trigger using a plugin organized in multiple files. The plugin directory must contain an `__init__.py` file. ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path "my_complex_plugin" \ --trigger-spec "every:5m" \ TRIGGER_NAME ``` The `--path` points to a directory in the server’s `plugin-dir` with the following structure: ``` my_complex_plugin/ ├── __init__.py # Required entry point ├── processors.py # Supporting modules └── utils.py ``` For more information about multifile plugins, see [Create your plugin file](/influxdb3/enterprise/plugins/#create-your-plugin-file). ### Upload and create a trigger with a local plugin Upload plugin files from your local machine and create a trigger in a single command. Requires admin token. ```bash # Upload single-file plugin influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path "/local/path/to/plugin.py" \ --upload \ --trigger-spec "every:1m" \ TRIGGER_NAME # Upload multifile plugin directory influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path "/local/path/to/plugin-dir" \ --upload \ --trigger-spec "table:TABLE_NAME" \ TRIGGER_NAME ``` The `--upload` flag transfers local files to the server’s plugin directory. This is useful for: * Local plugin development and testing * Deploying plugins without SSH access * Automating plugin deployment For more information, see [Upload plugins from local machine](/influxdb3/enterprise/plugins/#upload-plugins-from-local-machine). ### Create a trigger with additional arguments ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --trigger-arguments arg1=value1,arg2=value2 \ TRIGGER_NAME ``` ### Create a disabled trigger Create a trigger in a disabled state. ```bash influxdb3 create trigger \ --disabled \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ TRIGGER_NAME ``` Creating a trigger in a disabled state prevents it from running immediately. You can enable it later when you’re ready to activate it. ### Create a trigger with error handling Log the error to the service output and the `system.processing_engine_logs` table: ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --error-behavior log \ TRIGGER_NAME ``` Rerun the trigger if it fails: ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --error-behavior retry \ TRIGGER_NAME ``` Disable the trigger if it fails: ```bash influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --plugin-filename \ --trigger-spec table:TABLE_NAME \ --error-behavior disable \ TRIGGER_NAME ``` ### Pin a trigger to specific nodes in a cluster In a multi-node InfluxDB 3 Enterprise cluster, `--node-spec` selects which process nodes’ schedulers own the trigger. A process node is any node whose `--mode` includes `process` or `all`; setting [`--plugin-dir`](/influxdb3/enterprise/reference/config-options/#plugin-dir) adds `process` mode automatically. With the default `--node-spec all`, every process node owns the trigger and schedules it independently. For schedule triggers, this causes duplicate execution on every process node. For WAL triggers, every process node follows every ingester’s WAL through object storage, so the trigger fires once per process node for each WAL flush. For request triggers, the route exists only on the owning node(s); other process nodes return `404 not found`, and nodes without a Processing Engine return `405 Method Not Allowed`, since there’s no internal cross-node routing for the route itself. To pin a trigger to specific node(s), pass `--node-spec nodes:[,...]`: ```bash # Pin a schedule trigger to a process-capable node influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path schedule_rollup.py \ --trigger-spec "every:5s" \ --node-spec "nodes:NODE_ID" \ hourly_rollup # Pin a request trigger to a query-capable node (the node that serves HTTP) influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ --path request_top_n.py \ --trigger-spec "request:top_n" \ --node-spec "nodes:NODE_ID" \ top_n ``` The cluster validates the node IDs in `--node-spec` against current cluster membership at create time. A typo or unknown node ID is rejected with an `invalid node name ()` error. The cluster doesn’t validate the trigger type against the pinned node’s mode at create time. Pinning a trigger to a node without `--plugin-dir` configured succeeds, but the trigger doesn’t run there: a node that isn’t a process node has no Processing Engine, and a `--mode all` node without `--plugin-dir` logs an error when the trigger starts and fails every run placed on its own worker with `Node not configured with plugin directory`. Pin triggers only to nodes that set `--plugin-dir`. Choose the pinned node by what the trigger needs at execution: * **Schedule trigger**: Pin to a node with `process,query` mode if the plugin reads with `influxdb3_local.query()`; otherwise the call goes over the internode protocol to a query node that advertises an internode address (`--internode-bind-addr`). * **Request trigger**: Pin to the node(s) you want to serve external HTTP traffic. The `/api/v3/engine/` route only exists on pinned nodes; other process nodes return `404 not found`, and nodes without a Processing Engine return `405 Method Not Allowed`. For the full trigger execution model in a cluster, including scheduler state persistence and restart behavior, see [Run the Processing Engine in a cluster](/influxdb3/enterprise/admin/processing-engine-cluster/). | Option | | Description | | --- | --- | --- | | Option | | Description | | -H | --host | Host URL of the running InfluxDB 3 Enterprise server (default is http://127.0.0.1:8181 ) | | -d | --database | ( Required ) Name of the database to operate on | | | --token | ( Required ) Authentication token | | -p | --path | Path to plugin file or directory (single .py file or directory containing __init__.py for multifile plugins). Can be local path (with --upload ) or server path. Replaces --plugin-filename . | | | --upload | Upload local plugin files to the server. Requires admin token. Use with --path to specify local files. | | | --plugin-filename | (Deprecated: use --path instead) Name of the file, stored in the server’s plugin-dir , that contains the Python plugin code to run | | | --trigger-spec | Trigger specification: table: , all_tables , every: , cron: , or request: | | | --trigger-arguments | Additional arguments for the trigger, in the format key=value , separated by commas (for example, arg1=val1,arg2=val2 ) | | | --disabled | Create the trigger in disabled state (default: enabled) | | | --error-behavior | Error handling behavior: log , retry , or disable (default: log ) | | | --run-asynchronous | Run the trigger asynchronously, allowing multiple triggers to run simultaneously (default is synchronous) | | | --tls-ca | Path to a custom TLS certificate authority (for self-signed or internal certificates) | | | --tls-no-verify | Disable TLS certificate verification ( Not recommended in production , useful for self-signed certificates) | | -h | --help | Print help information | | | --help-all | Print detailed help information | | Option | | Description | | --- | --- | --- | | Option | | Description | | | --node-spec | Which process nodes’ schedulers own the trigger. Two value formats are supported: all (default) - every process node (a node with --plugin-dir configured) owns the trigger and schedules it independently, or nodes:[,..] - only the schedulers on the listed nodes own the trigger | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_DATABASE_NAME | --database | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify |