influxdb3-plugin-cli

Author-side CLI for the InfluxDB 3 Processing Engine plugin system — the influxdb3-plugin binary plus the embeddable PluginConfig type.

This crate is consumed by:

• end-user plugin authors invoking the standalone influxdb3-plugin binary
• the future phase-2 influxdb_pro integration mounting PluginConfig as a variant of the host's top-level command enum (Spec 2 § Phase-2 Embedding)

Commands

All commands accept --output {human, json}. The default is auto-detected from stdout's TTY status and the CI env var per Spec 2 § S2-14.

new <template> [path]

Scaffold a new plugin or index from a built-in template. Plugin templates: process_writes, process_scheduled_call, process_request. Index template: index.

influxdb3-plugin new process_writes ./my-plugin
influxdb3-plugin new index ./my-registry --artifacts-url https://plugins.example.com/artifacts

search [query]

Search a local registry index.json without mutating it or fetching artifacts. Human mode prints compact rows. JSON mode emits a stable envelope with one projected hit per plugin, including the selected version's published_at timestamp and visibility.

influxdb3-plugin search --index ./registry/index.json downsample
influxdb3-plugin search --index ./registry/index.json --trigger-type process_request
influxdb3-plugin search --index ./registry/index.json --database-version 3.2.0 --include-incompatible

info <name>

Inspect one plugin in a local registry index.json. Exact-version lookup uses --version <version>; name@version is not accepted for this command. Missing plugins and filtered-out name-only lookups are successful inspection outcomes with exit code 0.

influxdb3-plugin info --index ./registry/index.json downsampler
influxdb3-plugin info --index ./registry/index.json downsampler --version 1.2.0
influxdb3-plugin info --index ./registry/index.json legacy_rollup --include-yanked

validate [plugin-dir]

Run the manifest + cross-file checks. Accepts both multi-file plugins (with __init__.py) and single-file plugins (a sole .py file at the top level). Emits a { "diagnostics": [...] } JSON document on stdout in --output json mode regardless of pass / fail (Spec 2 § S2-15 validator idiom). Optional --index <path> adds the (name, version) uniqueness check (Spec 2 § S2-2).

influxdb3-plugin validate ./my-plugin
influxdb3-plugin validate ./my-plugin --index ./registry/index.json

package [plugin-dir]

Validate, archive, hash, and emit a derived index entry with current UTC published_at. Writes <out>/<name>-<version>.tar.gz and <out>/index.json. The input --index is read-only (Spec 2 § S2-11); --out must NOT resolve to the directory containing --index (S2-12).

influxdb3-plugin package ./my-plugin --index ./registry/index.json --out ./build

yank <name>@<version>

Toggle the yanked flag on an existing index entry while preserving its original published_at. Idempotent per Spec 2: re-yanking already-yanked (or --undo-ing not-yanked) is a successful no-op with an informational marker.

influxdb3-plugin yank downsampler@1.2.0 --index ./registry/index.json --out ./build
influxdb3-plugin yank downsampler@1.2.0 --undo --index ./registry/index.json --out ./build

--version

Top-level flag (Spec 2 § S2-21). Always emits one line of plain text regardless of --output:

influxdb3-plugin <version>, revision <sha>

The format matches the influxdb3 binary's build_version_string ({product}, {version}, revision {sha}), so when the SDK is embedded as influxdb3 plugin --version, the output is visually consistent with the host's top-level --version.

<sha> is the 40-character git commit hash from which the binary was built, sourced from (in precedence) the GIT_HASH env var, .cargo_vcs_info.json at the crate root, or git rev-parse HEAD. It degrades to the literal unknown only for uncontrolled rebuilds outside CI and outside cargo install.

Exit codes (Spec 2 § S2-18)

Codes 3 through 255 are reserved for additive future semantic codes; consumers reading only 0 / non-zero continue to work.

Embedding contract

PluginConfig is a clap-derived, semver-stable type. The phase-2 embedding shape is:

use clap::Parser;
use influxdb3_plugin_cli::PluginConfig;

# fn _example(host_argv: Vec<String>) -> anyhow::Result<()> {
let config = PluginConfig::try_parse_from(host_argv)?;
let runtime = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .build()?;
runtime.block_on(config.run())?;
# Ok(())
# }

Schema-type re-exports route through this crate so phase-2 consumers depend only on influxdb3-plugin-cli, satisfying Spec 2 § S2-10 and preventing parser drift from a parallel direct dependency on influxdb3-plugin-schemas.

Stability

Per Spec 2 § Stability, the public API of this crate — PluginConfig, its subcommand enum, pub async fn run(self) -> anyhow::Result<()>, clap attribute surface (arg names, env-var bindings, version declaration), schema-type re-exports, and the JSON output schema emitted in --output json mode — is covered by semver. Adding fields to a JSON output schema is a minor bump; renaming, removing, repurposing, or narrowing the type of an existing field is a major bump.

The crate is licensed MIT OR Apache-2.0 and is published to crates.io as the source-install channel for the influxdb3-plugin binary.

Dependency summary

Runtime: anyhow, clap (derive + env), tokio (current_thread + macros), serde, serde_json, semver, influxdb3-plugin-schemas, influxdb3-plugin-sdk.

Dev / test: assert_cmd, predicates, insta, rstest, tempfile, toml.

A build.rs script captures the full 40-char git commit SHA for the --version output (Spec 2 § S2-21), reading from GIT_HASH env when set, then .cargo_vcs_info.json at the crate root (Cargo's publish-time SHA capture), then git rev-parse HEAD. On full fallback the SHA degrades to the literal unknown rather than failing the build.