API Reference

This page documents the public APIs of cuenv’s Rust crates. For schema definitions, see Configuration Schema.

cuengine

The CUE evaluation engine crate provides the interface to evaluate CUE configurations through the Go FFI bridge.

CueEvaluatorBuilder

Builder for configuring a CueEvaluator. The usual entry point is CueEvaluator::builder(), which returns this type.

use cuengine::{CueEvaluator, RetryConfig};
use cuenv_core::manifest::Cuenv;
use std::{path::Path, time::Duration};

let evaluator = CueEvaluator::builder()
    .max_output_size(10 * 1024 * 1024)
    .retry_config(RetryConfig {
        max_attempts: 5,
        initial_delay: Duration::from_millis(50),
        max_delay: Duration::from_secs(2),
        exponential_base: 1.5,
    })
    .build()?;

let manifest: Cuenv = evaluator.evaluate_typed(Path::new("./project"), "cuenv")?;

Builder methods:

Method	Description
`new()` / `CueEvaluator::builder()`	Create a builder with default limits, retry config, and cache size
`max_path_length(len)`	Clamp the maximum accepted path length for evaluated directories
`max_package_name_length(len)`	Limit the package name length validated before evaluation
`max_output_size(bytes)`	Bound the JSON payload size returned from the bridge
`retry_config(RetryConfig)`	Customize retry behavior (see below)
`no_retry()`	Disable retries entirely
`cache_capacity(entries)`	Configure the in-memory evaluation cache (set to `0` to disable)
`cache_ttl(duration)`	Set the TTL for cached evaluation results
`build()`	Create a `CueEvaluator`

CueEvaluator

The main type for evaluating CUE packages.

use std::path::Path;

let evaluator = CueEvaluator::builder().no_retry().build()?;
let json = evaluator.evaluate(Path::new("./project"), "cuenv")?;

Key methods:

Method	Description
`builder()`	Returns a `CueEvaluatorBuilder`
`evaluate(&self, dir: &Path, package: &str)`	Evaluates the package and returns the raw JSON string from CUE
`evaluate_typed<T>(&self, dir: &Path, package: &str)`	Evaluates the package and deserializes it into `T`
`clear_cache()`	Drops any cached evaluation results held by this evaluator

`evaluate_cue_package`

The crate also exposes free functions when you don’t need a cached evaluator:

use cuengine::{evaluate_cue_package, evaluate_cue_package_typed};
use cuenv_core::manifest::Cuenv;
use std::path::Path;

let json = evaluate_cue_package(Path::new("./project"), "cuenv")?;
let manifest: Cuenv = evaluate_cue_package_typed(Path::new("./project"), "cuenv")?;

`get_bridge_version`

Fetches the Go bridge version string for diagnostics:

let version = cuengine::get_bridge_version()?;
println!("bridge reports {version}");

RetryConfig

Configuration for retry behavior on transient failures.

use cuengine::RetryConfig;
use std::time::Duration;

let config = RetryConfig {
    max_attempts: 4,
    initial_delay: Duration::from_millis(100),
    max_delay: Duration::from_secs(5),
    exponential_base: 2.0,
};

Fields:

Field	Type	Default	Description
`max_attempts`	`u32`	`3`	Maximum retry attempts
`initial_delay`	`Duration`	100 ms	Delay before the first retry
`max_delay`	`Duration`	10 s	Upper bound for the backoff delay
`exponential_base`	`f32`	`2.0`	Multiplier applied to each successive delay

cuenv-core

Core library with types for tasks, environments, hooks, and secrets.

Cuenv (Manifest)

The root configuration type parsed from CUE.

use cuenv_core::manifest::Cuenv;

let manifest: Cuenv = evaluator.evaluate()?;

Fields:

Field	Type	Description
`config`	`Option<Config>`	Global configuration
`env`	`Option<Env>`	Environment variables
`hooks`	`Option<Hooks>`	Shell hooks
`tasks`	`HashMap<String, Tasks>`	Task definitions
`workspaces`	`Option<Workspaces>`	Workspace configuration

Task Types

Task

Represents a single executable command pulled from CUE.

use cuenv_core::tasks::Task;
use serde_json::json;
use std::collections::HashMap;

let mut env = HashMap::new();
env.insert("RUST_LOG".into(), json!("info"));

let build = Task {
    command: "cargo".into(),
    args: vec!["build".into(), "--release".into()],
    shell: None,
    env,
    depends_on: vec!["lint".into(), "test".into()],
    inputs: vec!["src".into(), "Cargo.toml".into()],
    outputs: vec!["target/release/app".into()],
    inputs_from: None,
    external_inputs: None,
    workspaces: vec![],
    description: Some("Build release binaries".into()),
};

Fields:

Field	Type	Description
`command`	`String`	Executable to run
`args`	`Vec<String>`	Arguments for the command
`shell`	`Option<Shell>`	Override shell invocation (defaults to direct exec)
`env`	`HashMap<String, serde_json::Value>`	Task-specific environment additions
`depends_on`	`Vec<String>`	Other tasks that must finish first
`inputs`	`Vec<String>`	Files/globs tracked for hermetic execution
`outputs`	`Vec<String>`	Declared outputs that become cacheable artifacts
`inputs_from`	`Option<Vec<TaskOutput>>`	Consume outputs from other tasks in the same project
`external_inputs`	`Option<Vec<ExternalInput>>`	Consume outputs from another project in the repo
`workspaces`	`Vec<String>`	Workspace names to enable (see schema)
`description`	`Option<String>`	Human-friendly summary

TaskDefinition & TaskGroup

use cuenv_core::tasks::{TaskDefinition, TaskGroup};

let test_task = build.clone(); // assume another Task definition exists

let group = TaskDefinition::Group(TaskGroup::Sequential(vec![
    TaskDefinition::Single(Box::new(build.clone())),
    TaskDefinition::Single(Box::new(test_task)),
]));

TaskDefinition::Single(Task) represents one command.
TaskDefinition::Group(TaskGroup) represents sequential (Vec<TaskDefinition>) or parallel (HashMap<String, TaskDefinition>) sub-tasks.

Tasks

Tasks is the top-level map of task names to their definitions (flattened when parsed from CUE).

use cuenv_core::tasks::{TaskDefinition, Tasks};

let mut tasks = Tasks::new();
tasks.tasks.insert("build".into(), TaskDefinition::Single(Box::new(build)));

Environment

Env

Environment variable definitions.

use cuenv_core::environment::Env;

Environment values can be:

Simple values (strings, numbers, booleans)
Structured values with policies
Secret references

Hooks

Shell hook definitions.

use cuenv_core::hooks::{Hooks, ExecHook};

Fields:

Field	Type	Description
`on_enter`	`Option<Vec<ExecHook>>`	Hooks to run on directory entry
`on_exit`	`Option<Vec<ExecHook>>`	Hooks to run on directory exit

ExecHook

A single hook execution.

Fields:

Field	Type	Default	Description
`command`	`String`	required	Command to execute
`args`	`Vec<String>`	`[]`	Command arguments
`order`	`i32`	0	Execution order (lower = earlier)
`propagate`	`bool`	false	Export to child processes
`source`	`bool`	false	Source output as shell script
`inputs`	`Vec<String>`	`[]`	Input files for cache tracking

Secrets

Secret

Secret reference with exec-based resolution.

use cuenv_core::secrets::Secret;

Fields:

Field	Type	Description
`resolver`	`String`	Resolver type (always “exec”)
`command`	`String`	Command to retrieve secret
`args`	`Vec<String>`	Command arguments

Policy

Access control policy for secrets.

use cuenv_core::secrets::Policy;

Fields:

Field	Type	Description
`allow_tasks`	`Vec<String>`	Tasks that can access
`allow_exec`	`Vec<String>`	Exec commands that can access

Shell

Shell integration types.

Shell (enum)

Supported shell types.

use cuenv_core::shell::Shell;

match shell {
    Shell::Bash => { /* Bash shell */ }
    Shell::Zsh => { /* Zsh shell */ }
    Shell::Fish => { /* Fish shell */ }
    Shell::PowerShell => { /* PowerShell */ }
}

assert!(Shell::Bash.is_supported());
assert!(!Shell::PowerShell.is_supported());

Error Handling

Error

The main error type with diagnostic information.

use cuenv_core::Error;

Variants:

Variant	Description
`Configuration`	Configuration parsing/validation error
`Ffi`	FFI operation failure
`CueParse`	CUE parsing error
`Io`	I/O operation failure
`Task`	Task execution error
`Secret`	Secret resolution error
`Shell`	Shell integration error

All errors implement miette::Diagnostic for rich error reporting:

use miette::Result;

fn run() -> Result<()> {
    let evaluator = CueEvaluatorBuilder::new()
        .directory(".")
        .package("cuenv")
        .build()?;

    let manifest = evaluator.evaluate()?;
    Ok(())
}

Type Wrappers

PackageDir

Validated directory path.

use cuenv_core::PackageDir;
use std::path::Path;

let pkg_dir = PackageDir::try_from(Path::new("./project"))?;

PackageName

Validated CUE package name.

use cuenv_core::PackageName;

let pkg_name = PackageName::try_from("cuenv")?;

Cache

Task cache helpers

The task cache utilities live under cuenv_core::cache::tasks.

use cuenv_core::cache::tasks::{
    compute_cache_key, lookup, materialize_outputs, CacheKeyEnvelope,
};
use std::{collections::BTreeMap, path::Path};

let envelope = CacheKeyEnvelope {
    inputs: BTreeMap::new(),
    command: "cargo".into(),
    args: vec!["build".into()],
    shell: None,
    env: BTreeMap::new(),
    cuenv_version: cuenv_core::VERSION.to_string(),
    platform: format!("{}-{}", std::env::consts::OS, std::env::consts::ARCH),
    workspace_lockfile_hashes: None,
    workspace_package_hashes: None,
};

let (key, _) = compute_cache_key(&envelope)?;
if let Some(entry) = lookup(&key, None) {
    println!("cache hit stored at {}", entry.path.display());
    materialize_outputs(&key, Path::new("artifacts"), None)?;
}

Additional helpers such as save_result, record_latest, and lookup_latest are available when integrating custom executors with cuenv’s cache layout.

CLI Exit Codes

The cuenv CLI uses structured exit codes:

Code	Name	Description
0	Success	Command completed successfully
2	ConfigError	CLI/configuration error (`CliError::Config`)
3	EvalError	Evaluation, task, or other runtime error (`CliError::Eval` / `CliError::Other`)

API Reference

cuengine

CueEvaluatorBuilder

CueEvaluator

evaluate_cue_package

get_bridge_version

RetryConfig

cuenv-core

Cuenv (Manifest)

Task Types

Task

TaskDefinition & TaskGroup

Tasks

Environment

Env

Hooks

Hooks

ExecHook

Secrets

Secret

Policy

Shell

Shell (enum)

Error Handling

Error

Type Wrappers

PackageDir

PackageName

Cache

Task cache helpers

CLI Exit Codes

See Also

`evaluate_cue_package`

`get_bridge_version`