CLI Reference¶

Flowcept’s CLI is available immediatelly after you run pip install flowcept.

flowcept --help

Shows all available commands with their helper description and arguments.

Usage pattern¶

flowcept --<function-name-with-dashes> [--<arg-name-with-dashes>=<value>] ...

Rules: - Commands come from flowcept.cli public functions. - Underscores become hyphens (e.g., stream_messages → --stream-messages). - Bool params work as flags (present/absent). Other params require a value.

Configuration Profiles¶

Flowcept provides quick settings profiles to switch between common runtime modes:

flowcept --config-profile full-online
flowcept --config-profile full-telemetry
flowcept --config-profile mq-only
flowcept --config-profile full-offline
flowcept --config-profile mq-only-no-flush

Settings bootstrap¶

Use --init-settings to create a file, then optionally apply a profile:

flowcept --init-settings
flowcept --init-settings --full
flowcept --config-profile full-online

Meaning:

flowcept --init-settings: create a minimal file from DEFAULT_SETTINGS.
flowcept --init-settings --full: copy resources/sample_settings.yaml.
flowcept --config-profile ...: modify the existing file in place.

Adapter flags are additive:

flowcept --init-settings --dask -y
flowcept --init-settings --mlflow -y
flowcept --init-settings --tensorboard -y

They add adapters.<name> to the current settings file instead of replacing it.

Behavior: - Prints the exact settings keys that will change and their new values. - Prompts for confirmation before writing changes. - Writes to FLOWCEPT_SETTINGS_PATH when set; otherwise writes to ~/.flowcept/settings.yaml.

Use -y (or --yes) to skip the confirmation prompt:

flowcept --config-profile full-online -y

Current profile values:

full-online: - project.db_flush_mode: online - mq.enabled: true - kv_db.enabled: true - databases.mongodb.enabled: true - databases.lmdb.enabled: false - db_buffer.insertion_buffer_time_secs: 5
full-telemetry: - enables CPU, per-CPU, process, memory, disk, network, and machine telemetry - telemetry_capture.gpu: null
mq-only: - project.db_flush_mode: online - mq.enabled: true - kv_db.enabled: false - databases.mongodb.enabled: false - databases.lmdb.enabled: false - Use Flowcept(check_safe_stops=False) with this profile.
full-offline: - project.db_flush_mode: offline - project.dump_buffer.enabled: true - mq.enabled: false - kv_db.enabled: false - databases.mongodb.enabled: false - databases.lmdb.enabled: false
mq-only-no-flush: - project.db_flush_mode: offline - project.dump_buffer.enabled: true - mq.enabled: true - kv_db.enabled: false - databases.mongodb.enabled: false - databases.lmdb.enabled: false - Tasks accumulate locally during the run and are bulk-published to MQ in a single

end-of-run flush. A local JSONL copy is also written. No persistent DB is required.
- Use Flowcept(check_safe_stops=False) with this profile.

Environment variables can override settings values at runtime. This matters for keys such as MONGO_ENABLED, LMDB_ENABLED, LMDB_PATH, MQ_ENABLED, MQ_TYPE, MQ_PORT, and DB_FLUSH_MODE.

Available commands¶

flowcept.cli.show_settings()¶: Show Flowcept configuration.

flowcept.cli.init_settings(full: bool = False, yes: bool = False, dask: bool = False, mlflow: bool = False, tensorboard: bool = False)¶

Create or extend the user settings file.

Parameters¶

fullbool, optional: If true, copy resources/sample_settings.yaml. Otherwise create the minimal settings file from flowcept.configs.DEFAULT_SETTINGS.
yesbool, optional: Auto-confirm overwrite if the settings file already exists.
daskbool, optional: Add default dask adapter settings under adapters.dask.
mlflowbool, optional: Add default mlflow adapter settings under adapters.mlflow.
tensorboardbool, optional: Add default tensorboard adapter settings under adapters.tensorboard.

Notes¶

If FLOWCEPT_SETTINGS_PATH is set, that path is used instead of ~/.flowcept/settings.yaml.
Adapter flags are additive: if the target file already exists, Flowcept reuses it and only writes adapter sections.
–full only copies the full sample file. It does not apply a runtime profile.

flowcept.cli.apply_config_profile(config_profile: str, yes: bool = False)¶

Apply a settings profile overlay to the user settings file.

Parameters¶

config_profilestr: Profile name. Supported values: full-online, full-telemetry, mq-only, full-offline, mq-only-no-flush.
yesbool, optional: If true, skip confirmation prompt and apply changes immediately.

Notes¶

Profiles modify the existing file in place. They do not create a separate profile file and they do not bypass runtime environment-variable overrides.

flowcept.cli.version()¶: Returns this Flowcept’s installation version.

flowcept.cli.stream_messages(messages_file_path: str | None = None, keys_to_show: List[str] = None)¶

Listen to Flowcept’s message stream and optionally echo/save messages.

Parameters.¶

messages_file_pathstr, optional: If provided, append each message as JSON (one per line) to this file. If the file already exists, a new timestamped file is created instead.
keys_to_showList[str], optional: List of object keys to show in the prints. Use comma-separated list: –keys-to-show ‘activity_id’,’workflow_id’

flowcept.cli.start_consumption_services(bundle_exec_id: str = None, check_safe_stops: bool = False, consumers: List[str] = None)¶

Start services that consume data from a queue or other source.

Parameters¶

bundle_exec_idstr, optional: The ID of the bundle execution to associate with the consumers.
check_safe_stopsbool, optional: Whether to check for safe stopping conditions before starting.
consumerslist of str, optional: List of consumer IDs to start. If not provided, all consumers will be started.

flowcept.cli.stop_consumption_services()¶: Stop the running consumption services process gracefully via MQ stop message.

flowcept.cli.start_services(with_mongo: bool = False)¶

Start Flowcept services (optionally including MongoDB).

Parameters¶

with_mongobool, optional: Whether to also start MongoDB.

flowcept.cli.stop_services()¶: Stop Flowcept services.

flowcept.cli.workflow_count(workflow_id: str)¶

Count number of documents in the DB.

Parameters¶

workflow_idstr: The ID of the workflow to count tasks for.

flowcept.cli.query(filter: str, project: str = None, sort: str = None, limit: int = 0)¶

Query the MongoDB task collection with an optional projection, sort, and limit.

Parameters¶

filterstr: A JSON string representing the MongoDB filter query.
projectstr, optional: A JSON string specifying fields to include or exclude in the result (MongoDB projection).
sortstr, optional: A JSON string specifying sorting criteria (e.g., ‘[[“started_at”, -1]]’).
limitint, optional: Maximum number of documents to return. Default is 0 (no limit).

Returns¶

List[dict]: A list of task documents matching the query.

flowcept.cli.get_task(task_id: str)¶

Query the Document DB to retrieve a task.

Parameters¶

task_idstr: The identifier of the task.

flowcept.cli.start_agent()¶: Start Flowcept agent.

flowcept.cli.start_agent_gui(port: int = None)¶

Start Flowcept agent GUI service.

Parameters¶

portint, optional: The default port is 8501. Use –port if you want to run the GUI on a different port.

flowcept.cli.agent_client(tool_name: str, kwargs: str = None)¶

Agent Client.

Parameters.¶

tool_namestr: Name of the tool
kwargsstr, optional: A stringfied JSON containing the kwargs for the tool, if needed.

flowcept.cli.check_services()¶

Run a full diagnostic test on the Flowcept system and its dependencies.

This function: - Prints the current configuration path. - Checks if required services (e.g., MongoDB, agent) are alive. - Runs a test function wrapped with Flowcept instrumentation. - Verifies MongoDB insertion (if enabled). - Verifies agent communication and LLM connectivity (if enabled).

Returns¶

None: Prints diagnostics to stdout; returns nothing.

flowcept.cli.start_mongo() → None¶

Start a MongoDB server using paths configured in the settings file.

Looks up:

databases:

mongodb:

bin : str (required) path to the mongod executable
db_path: str, required path to the db data directory
log_path : str, optional (adds –fork –logpath)
lock_file_path : str, optional (adds –pidfilepath)

Builds and runs the startup command.

flowcept.cli.start_redis() → None¶

Start a Redis server using paths configured in settings.

Looks up:

mq:

bin : str (required) path to the redis-server executable
conf_file : str, optional (appended as the sole argument)

Builds and runs the command via _run_command(cmd, check_output=True).

flowcept.cli.stop_redis() → None¶: Stop the running Redis server via redis-cli shutdown.

flowcept.cli.start_webservice(webservice_host: str = '127.0.0.1', webservice_port: str = '8008')¶

Start the Flowcept FastAPI webservice locally.

Parameters¶

webservice_hoststr, optional: Host interface to bind (default: 127.0.0.1).
webservice_portint, optional: Port to bind (default: 8008).

flowcept.cli.generate_report(format: str = 'markdown', output_path: str = None, input_path: str = None, workflow_id: str = None)¶

Generate a provenance report from a JSONL buffer file or a workflow ID.

Parameters¶

formatstr, optional: Output format: markdown (default) or pdf.
output_pathstr, optional: Output report path. If omitted, defaults to PROVENANCE_CARD.md for markdown and PROVENANCE_REPORT.pdf for pdf.
input_pathstr, optional: Path to the Flowcept JSONL buffer file.
workflow_idstr, optional: Workflow ID to query from the configured database (MongoDB first, then LMDB).