df-cli Command Line Reference

This page describes the implemented command-line surface of df-cli. It is aligned with the parser in src/DFProcessor.cpp.

Basic Syntax

df-cli [options] <command> [arguments]

Global Options

Option	Description
`--version`	Display version and health information about this df-cli installation.
`--help`	Display help information.
`--force-color`	Force colorized terminal output.
`--studiobuild`	Enable Studio-oriented output behavior.

Top-Level Commands

`system`

Display system and health information about the current df-cli installation.

df-cli system

`help`

Display help for df-cli.

df-cli help

`login`

Log into a DataFlex package repository.

df-cli login [--endpoint <url>] [--access-token <token>] [--refresh-token <token>]

Option	Description
`--endpoint <url>`	Repository endpoint to log into.
`--access-token <token>`	Authenticate directly with an access token.
`--refresh-token <token>`	Optional refresh token used with `--access-token`.

`logout`

Log out of a DataFlex package repository.

df-cli logout [--endpoint <url>]

Option	Description
`--endpoint <url>`	Repository endpoint to log out from.

`create`

Create a new workspace.

df-cli create <workspace_name> [-d <description>] [-o <output_dir>]

Argument / Option	Required	Description
`<workspace_name>`	Yes	Name of the workspace to create.
`-d`, `--desc <text>`	No	Description for the workspace.
`-o`, `--output <dir>`	No	Parent directory for the new workspace.

`convert`

Convert a legacy INI .sws file to JSON.

df-cli convert <workspace_file> [-r] [--df <version>]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to convert.
`-r`, `--recursive`	No	Also convert local dependencies recursively.
`--df <version>`	No	Override the DataFlex version written to the converted workspace.

`config`

Open, inspect, or repair a workspace.

df-cli config <workspace_file> [--no-dependencies] [--json] [--repair]
df-cli <workspace_file>

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to open.
`--no-dependencies`	No	Do not load dependencies.
`--json`	No	Output raw JSON instead of human-readable text.
`--repair`	No	Attempt to repair the workspace before displaying it.

`build`

Build a workspace or a target project.

df-cli build <workspace_file> [options]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to build.
`-t`, `--target <name>`	No	Specific project within the workspace to build.
`-r`, `--rebuild`	No	Force the build even if no changes are detected.
`-f`, `--force`	No	Skip dependency cache verification and file installation, and continue even if workspace loading fails.
`-v`, `--verbose`	No	Enable verbose output during the build process.
`-c`, `--check`	No	Check whether a build is needed without performing the build.
`--toolchain <name>`	No	Specify the toolchain to use.
`--no-warnings`	No	Disable warnings during the build process.
`-w`, `--write-errors`	No	Write compiler errors to an ERR file.
`-D`, `--define <key=value>`	No	Define a preprocessor key-value pair. Can be specified multiple times.
`-I`, `--include <path>`	No	Add an include path for the compiler. Can be specified multiple times.
`--restart-webapp`	No	(Windows only) Stop the matching WebApp Server application before building; restart it after a successful build.

`build-file`

Build a single DataFlex source file.

df-cli build-file <source_file> [options]

Argument / Option	Required	Description
`<source_file>`	Yes	DataFlex source file to build.
`--output-dir <dir>`	No	Output directory for the compiled program. Note that when not specified, the output will be created in the directory where the source file is located.
`--precompile`	No	Precompile the source file.
`--workspace <file>`	No	Workspace file used for include paths.
`--suffix32 <suffix>`	No	Suffix for 32-bit compiled programs.
`--suffix64 <suffix>`	No	Suffix for 64-bit compiled programs.
`--cfg <file>`	No	Configuration (.cfg) file for linking resources (icons, manifest, version info).
`-r`, `--rebuild`	No	Force the build even if no changes are detected.
`-f`, `--force`	No	Continue even if workspace loading fails.
`-v`, `--verbose`	No	Enable verbose output during the build process.
`-c`, `--check`	No	Check whether a build is needed without performing the build.
`--toolchain <name>`	No	Specify the toolchain to use.
`--no-warnings`	No	Disable warnings during the build process.
`-w`, `--write-errors`	No	Write compiler errors to an ERR file.
`-D`, `--define <key=value>`	No	Define a preprocessor key-value pair. Can be specified multiple times.
`-I`, `--include <path>`	No	Add an include path for the compiler. Can be specified multiple times.

`run`

Build a runnable workspace project when needed and launch it.

df-cli run <workspace_file> [project] [--no-compile]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to run.
`[project]`	No	Project to run. Required when the workspace has multiple runnable non-test projects.
`--no-compile`	No	Skip compilation and run the last compiled output directly. The output executable must already exist; if it is missing, the command fails. `df-cli` forwards the executable's exit code.

`toolchain`

Inspect installed DataFlex toolchains.

`toolchain list`

df-cli toolchain list

`toolchain info`

df-cli toolchain info <name>

Argument	Required	Description
`<name>`	Yes	Toolchain version to inspect.

Package Commands

`package search`

Search for packages compatible with the workspace's DataFlex version.

df-cli package search <workspace_file> [search_term] [filters...]

Argument	Required	Description
`<workspace_file>`	Yes	Workspace file (`.sws`) whose DataFlex version scopes the search.
`[search_term]`	No	Search term. Omit to list all packages.
`[filters...]`	No	Optional `key=value` filters.

`package details`

Display detailed information about a specific package.

df-cli package details <library>

Argument	Required	Description
`<library>`	Yes	Package or library to inspect.

`package install`

Install a package into a workspace.

df-cli package install <workspace_file> <package_string>

Argument	Required	Description
`<workspace_file>`	Yes	Workspace file to install into.
`<package_string>`	Yes	Package string, Git URL, or local `.sws` workspace path. Packed package archives are not accepted.

`package update`

Check whether newer compatible versions are available for installed packages.

df-cli package update <workspace_file> [package_string]

Argument	Required	Description
`<workspace_file>`	Yes	Workspace file to check for updates.
`[package_string]`	No	Specific package to check.

For repository packages, update reports only versions that are compatible with the current workspace: the version must satisfy the workspace's dependency constraint, the installed package graph's shared dependency constraints, and the workspace DataFlex version supported by the package metadata. A newer published version can therefore be hidden if it would require an incompatible transitive dependency or a different DataFlex version.

`package upgrade`

Upgrade installed packages to newer compatible versions.

df-cli package upgrade <workspace_file> [package_string] [-y]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to upgrade packages in.
`[package_string]`	No	Specific package to upgrade.
`-y`, `--yes`	No	Automatically confirm upgrade without prompting.

upgrade applies the compatible version selected by update, then updates the workspace and lock file only after the dependency tree is resolved successfully.

`package uninstall`

Remove an installed package from a workspace.

df-cli package uninstall <workspace_file> <package_string> [--force]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to uninstall from.
`<package_string>`	Yes	Package to uninstall.
`--force`	No	Force uninstall even if other packages depend on it.

`package pack`

Create a distributable package archive from a workspace.

df-cli package pack <workspace_file>

Argument	Required	Description
`<workspace_file>`	Yes	Workspace file to pack.

`package push`

Push a packed workspace to a package repository.

df-cli package push <workspace_file> <repository>/<package> [-y]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to push.
`<repository>/<package>`	Yes	Repository and package identity in `repository/package` form.
`-y`, `--yes`	No	Confirm the push without prompting.

Authenticate with df-cli login before running package push.

WebApp Server Commands

Inspect and control DataFlex WebApp Server applications. Windows only. See WebApp_Server.md for full details.

`webapp list`

List all registered WebApp Server applications and their status.

df-cli webapp [list]

Running df-cli webapp with no subcommand is equivalent to webapp list (usage is also printed first).

Status on DataFlex < 26.0. These versions ship a wasclnt.dll without the enabled-state query, so df-cli falls back to a no-admin liveness probe on the app's executable: a running worker → running; no worker → stopped only when the app keeps a resident worker pool (UseConnectorPool=1 and MinPool >= 1), otherwise unknown; any probe error → unknown. unknown means the state could not be determined — not that the app is broken; it still installs, compiles, and runs normally. See WebApp Server Management for the full breakdown.

`webapp start`

Start a WebApp Server application in-memory (transient).

df-cli webapp start <id>

Argument	Required	Description
`<id>`	Yes	Application identifier, e.g. `99.0/WebOrder`.

`webapp stop`

Stop a WebApp Server application in-memory. Blocks until all worker processes have exited.

df-cli webapp stop <id>

Argument	Required	Description
`<id>`	Yes	Application identifier, e.g. `99.0/WebOrder`.

`webapp restart`

Stop then start a WebApp Server application.

df-cli webapp restart <id>

Argument	Required	Description
`<id>`	Yes	Application identifier, e.g. `99.0/WebOrder`.

`webapp enable`

Persistently enable a WebApp Server application by writing Disable=0 to the registry. Requires Administrator. Does not immediately start the application in-memory.

df-cli webapp enable <id>

Argument	Required	Description
`<id>`	Yes	Application identifier, e.g. `99.0/WebOrder`.

`webapp disable`

Persistently disable a WebApp Server application by writing Disable=1 to the registry. Requires Administrator. Does not immediately stop active sessions.

df-cli webapp disable <id>

Argument	Required	Description
`<id>`	Yes	Application identifier, e.g. `99.0/WebOrder`.

Cache Commands

`cache`

Inspect and manage the shared package cache.

df-cli cache [--prune [<library>]] [--pin <name>] [--unpin <name>] [--verify [<library>]]

Option	Description
`--prune [<name>]`	Remove eligible cache entries.
`--pin <name>`	Pin a cache entry so it is not pruned.
`--unpin <name>`	Remove the pin from a cache entry.
`--verify [<name>]`	Verify cache entry integrity.

SBOM

`sbom`

Generate a Software Bill of Materials for a workspace.

df-cli sbom <workspace_file> <output_file>

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to generate the SBOM for.
`<output_file>`	Yes	Output file to write.
Output format	—	df-cli currently generates CycloneDX JSON only.