Skip to main content

flowctl CLI Reference

Command-line tool for developing, testing, and managing Beacon Tower flows.

Installation​

Both flowctl and btscript are included in the dev kit. Download the latest version from github.com/beacontower/tools/releases. See Local Flow Development for full setup instructions.

Individual tool updates are also available from the same releases page.

Global Options​

All commands accept these options:

OptionDescription
--output, -o <format>Output format: table (default), json, yaml
--environment, -e <name>Target environment (default: local)
--verbose, -vVerbose output for debugging
--retries <count>Override retry count (0 to disable)

Example:

flowctl --output json instance list
flowctl -e staging artifact list

Environment Management​

flowctl env start​

Start the local Docker environment.

flowctl env start [--skip-bootstrap]

Starts all services defined in the Docker Compose configuration. With --skip-bootstrap, skips JetStream stream setup.

flowctl env stop​

Stop services. Data volumes are preserved.

flowctl env stop

flowctl env status​

Check health of all services.

flowctl env status

flowctl env logs​

View service logs.

flowctl env logs [service]

Examples:

flowctl env logs              # All services
flowctl env logs flow-service # Specific service
flowctl env logs silo         # Silo logs

flowctl env reset​

Stop, remove volumes, and start fresh. Destructive — deletes all data.

flowctl env reset [--force]

flowctl env bootstrap​

Re-run JetStream stream and consumer setup.

flowctl env bootstrap

Project Workflow​

flowctl project init​

Create a new flow project in the current directory.

flowctl project init [--no-dev]

Creates flowproject.yaml, flows/, tasks/, functions/, models/, and tests/ directories.

flowctl project build​

Compile all .bts files to .cs using the btscript compiler.

flowctl project build

flowctl project upload​

Build and upload all artifacts to the Flow Service.

flowctl project upload

flowctl project switch​

Change the active flow for development.

flowctl project switch <flow>

Updates flowproject.yaml dev configuration.

flowctl project dev​

Full dev cycle: build, upload, create/migrate instance, tail outputs.

flowctl project dev [--watch] [--no-tail]
  • --watch — Watch for file changes and auto-rebuild
  • --no-tail — Skip output tailing

flowctl dev​

Alias for flowctl project dev.

flowctl dev [--watch] [--no-tail]

Asset Management​

flowctl asset init​

Initialize an asset in the Orleans cluster.

flowctl asset init <assetId> --model <model.yaml>
flowctl asset init <assetId> --generic
  • --model — Path to a DTDL model YAML file
  • --generic — Initialize with a generic model (accepts any telemetry)

Examples:

flowctl asset init pump-042 --model models/pump.model.yaml
flowctl asset init dev-sensor --generic

flowctl asset list​

List all initialized assets.

flowctl asset list

flowctl asset get​

Show asset details (endpoints, bindings).

flowctl asset get <assetId>

flowctl asset update​

Update asset endpoints from a model.

flowctl asset update <assetId> --model <model.yaml>

flowctl asset remove​

Remove an asset from the Orleans cluster.

flowctl asset remove <assetId>

Artifact Management​

flowctl artifact upload​

Upload a flow artifact (.cs, .bts, or .dll).

flowctl artifact upload <file> [--version <ver>] [--bump <patch|minor|major>]

Examples:

flowctl artifact upload build/flow.cs
flowctl artifact upload build/flow.cs --version 1.2.0
flowctl artifact upload build/flow.cs --bump minor

flowctl artifact list​

List all uploaded artifacts.

flowctl artifact list

flowctl artifact get​

Get artifact details by BTI.

flowctl artifact get <bti>

Example:

flowctl artifact get "btf:temp-conversion;1.0.0"

flowctl artifact delete​

Delete an artifact.

flowctl artifact delete <bti> [--force]

--force skips the confirmation prompt but does not bypass the instance safety check. The delete operation will fail if any instances are still using the artifact, even with --force.

flowctl artifact diff​

Compare two artifact versions.

flowctl artifact diff <from-bti> <to-bti>

flowctl artifact migrate​

Migrate all instances of an artifact to a new version.

flowctl artifact migrate <bti> --to <target-bti> [--keep-state] [--force]

flowctl artifact validate​

Validate a flow file without uploading.

flowctl artifact validate <file>

Instance Management​

flowctl instance create​

Create a flow instance bound to an asset.

flowctl instance create <id> --bti <bti> --asset <assetId> [--input <name=subject>...]

Example:

flowctl instance create monitor-1 \
  --bti "btf:pump-monitor;1.0.0" \
  --asset pump-042

flowctl instance list​

List flow instances.

flowctl instance list [--asset <id>] [--bti <bti>] [--status <status>]

flowctl instance get​

Get instance details.

flowctl instance get <id>

flowctl instance delete​

Delete an instance.

flowctl instance delete <id> [--force]

flowctl instance send​

Send an input value to an instance. The signal must match an input binding in the flow.

flowctl instance send <id> <signal> <value> [--provider-id <id>]

Examples:

flowctl instance send monitor-1 temperature 85.5
flowctl instance send monitor-1 threshold 100.0

flowctl instance watch​

Watch instance output in real time.

flowctl instance watch <id> [--output-only] [--events-only]

Press Ctrl+C to stop.

flowctl instance state​

Inspect instance execution state.

flowctl instance state <id>

# Subcommands
flowctl instance state backups <id>
flowctl instance state restore <id> <backup-id>

flowctl instance logs​

View instance logs.

flowctl instance logs <id> [--limit <n>] [--since <time>] [-f]

flowctl instance events​

Tail lifecycle events for an instance.

flowctl instance events <id>

flowctl instance pause / resume / restart​

Control instance execution.

flowctl instance pause <id>
flowctl instance resume <id>
flowctl instance restart <id>

flowctl instance migrate​

Migrate an instance to a new artifact version.

flowctl instance migrate <id> --to <bti> [--keep-state] [--force]

flowctl instance update​

Update instance input mappings.

flowctl instance update <id> --input <name=subject> [--input <name=subject>...]

flowctl instance purge​

Purge instance data for clean test iterations.

flowctl instance purge <id> --outputs [-y]   # Clear outputs and events
flowctl instance purge <id> --state [-y]     # Clear state (fresh restart)
flowctl instance purge <id> --all [-y]       # Clear everything

NATS Operations​

flowctl nats sub​

Subscribe to a NATS subject. Supports wildcards: * (single token), > (multiple tokens).

flowctl nats sub <subject>

Examples:

flowctl nats sub "events.>"         # All flow events
flowctl nats sub "telemetry.>"      # All telemetry
flowctl nats sub "output.>"         # All flow outputs

flowctl nats pub​

Publish a message to a NATS subject.

flowctl nats pub <subject> <data> [--header <key=value>...]

Data can be a JSON string or @filename to read from a file.

Example:

flowctl nats pub "telemetry.flowctl::pump-042" \
  '{"temperature": 85.5}' \
  --header "providerId=flowctl" \
  --header "providerClientId=pump-042" \
  --header "messageType=ProviderClientTelemetry"

flowctl nats replay​

Replay messages from a JetStream stream.

flowctl nats replay <subject> --from <seq|timestamp> [--to <seq|timestamp>] [--take <n>]

Examples:

flowctl nats replay "events.>" --from 1 --take 10
flowctl nats replay "telemetry.>" --from 2026-02-09T10:00:00Z

flowctl nats watch​

Watch subjects for an instance or asset.

flowctl nats watch --instance <id>
flowctl nats watch --asset <id>

flowctl nats streams​

List JetStream streams with message counts.

flowctl nats streams

flowctl nats consumers​

List consumers for a JetStream stream.

flowctl nats consumers <stream>

Example:

flowctl nats consumers TELEMETRY

flowctl nats purge​

Purge messages from a stream.

flowctl nats purge <stream> [--yes]
flowctl nats purge --all [--yes]

Data Feeding​

flowctl feed​

Feed telemetry from a JSONL file or generate synthetic data.

# From file
flowctl feed <file.jsonl> [--speed <multiplier>] [--dry-run]

# Generate data
flowctl feed --generate <type> --asset <id> --signal <name> --count <n> [options]

Generators: sine, sawtooth, random, step, ramp

Generator options:

OptionDescription
--count <n>Number of data points (default: 100)
--min <val>Minimum value
--max <val>Maximum value
--amplitude <val>Amplitude for sine waves
--offset <val>Baseline offset for sine waves
--period <val>Period for sine/sawtooth
--interval <ms>Milliseconds between values
--from <val>Start value for ramp
--to <val>End value for ramp
--values <csv>Values for step generator

Examples:

flowctl feed data.jsonl --speed 10x
flowctl feed --generate sine --asset pump-042 --signal temperature --count 100
flowctl feed --generate random --asset pump-042 --signal pressure --count 50 --min 0 --max 100

JSONL format:

{"assetId": "pump-042", "signal": "temperature", "value": 85.5}
{"assetId": "pump-042", "signal": "temperature", "value": 82.1, "delay": "100ms"}
{"assetId": "pump-042", "signal": "pressure", "value": 150.0, "delay": "50ms"}

Advanced feeding options:

OptionDescription
--via-bindingsRoute through asset grain bindings (runs transforms)
--endpoint <id>Feed to a specific endpoint
--provider-id <id>Override provider ID (default: flowctl)
--dry-runShow what would be published without sending
--validateValidate endpoint formats without sending

Replay​

flowctl replay​

Replay historical messages for an instance.

flowctl replay <instance-id> [--from <time|seq>] [--to <time|seq>] [--take <n>] [--speed <mult>]

Examples:

flowctl replay monitor-1 --from 2026-02-09T10:00:00Z --take 100
flowctl replay monitor-1 --from 1 --take 50 --speed 10x

Model Operations​

flowctl model validate​

Validate a DTDL model file.

flowctl model validate <file>

flowctl model show​

Display parsed model information.

flowctl model show <file>

flowctl model new​

Create a model from template.

flowctl model new <name> [--force]

Scaffolding​

flowctl new​

Create new artifacts from templates.

flowctl new flow <name> [--cs] [--force]
flowctl new task <name> [--force]
flowctl new function <name> [--force]
  • --cs — Generate C# scaffold instead of BtScript
  • --force — Overwrite existing file

Testing​

flowctl test​

Run test scenarios.

flowctl test <file.test.yaml> [--record] [--timeout <duration>]
flowctl test --all [-n <prefix>]
  • --record — Record outputs as expected values
  • --all — Run all tests in tests/ directory
  • -n, --namespace <prefix> — Subject prefix for test isolation
  • --timeout <duration> — Override timeout (e.g., 30s, 1m)

Ingress Control​

flowctl ingress status​

Show ingress processor status.

flowctl ingress status [--stream <name>] [--consumer <name>]

Defaults: --stream TELEMETRY, --consumer asset-processor-0

flowctl ingress pause​

Pause telemetry processing.

flowctl ingress pause [--stream <name>] [--consumer <name>] [--duration <duration>]

Defaults: --stream TELEMETRY, --consumer asset-processor-0

flowctl ingress resume​

Resume telemetry processing.

flowctl ingress resume [--stream <name>] [--consumer <name>]

Defaults: --stream TELEMETRY, --consumer asset-processor-0

Utilities​

flowctl doctor​

Check environment health and connectivity.

flowctl doctor

flowctl version​

Show version and build information.

flowctl version

flowctl completion​

Generate shell completion scripts.

flowctl completion bash       # source <(flowctl completion bash)
flowctl completion zsh        # source <(flowctl completion zsh)
flowctl completion fish       # flowctl completion fish > ~/.config/fish/completions/flowctl.fish
flowctl completion powershell # flowctl completion powershell >> $PROFILE

Exit Codes​

CodeMeaning
0Success
1General error
2Network error
3Authentication error
4Conflict
5Not found
6Migration failed
7Partial success
8Timeout
10Environment not ready

Configuration​

User Configuration​

~/.flowctl/config.yaml:

default_environment: local

environments:
  local:
    flow_service: http://localhost:5000
    nats: nats://localhost:4222
    orleans:
      postgres_connection: "Host=localhost;Port=5432;Database=orleans;Username=orleans;Password=orleans"
      cluster_id: docker-cluster
      service_id: docker-cluster

Project Configuration​

flowproject.yaml:

name: my-project
version: 1.0.0

artifacts:
  flows: flows/*
  tasks: tasks/*
  functions: functions/*

dev:
  active_flow: flows/pump-monitor.bts
  instance_id: dev-1
  asset_id: pump-042
  provider_id: flowctl

Environment Variables​

VariableDescription
FLOWCTL_ENVIRONMENTOverride default environment
FLOWCTL_OUTPUTOverride output format
FLOWCTL_VERBOSEEnable verbose output (1/true/yes)
NATS_URLNATS server URL
FLOW_SERVICE_URLFlow Service API URL