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]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to convert.
`-r`, `--recursive`	No	Also convert local dependencies recursively.

`config`

Open, inspect, or repair a workspace.

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

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to open.
`--no-dependencies`	No	Do not load dependencies.
`--output-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.
`-p`, `--project <name>`	No	Specific project within the workspace to build.
`-t`, `--target <name>`	No	Alias for `--project`.
`-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.

`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.
`--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.
`-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.

`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 in the configured package repository.

df-cli package search [search_term] [filters...]

Argument	Required	Description
`[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 packed package path.

`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.

`package upgrade`

Upgrade installed packages to newer compatible versions.

df-cli package upgrade <workspace_file> [package_string]

Argument	Required	Description
`<workspace_file>`	Yes	Workspace file to upgrade packages in.
`[package_string]`	No	Specific package to upgrade.

`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> [-y]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to push.
`<repository>`	Yes	Repository name or URL.
`-y`, `--yes`	No	Confirm the push without prompting.

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> [--format <format>]

Argument / Option	Required	Description
`<workspace_file>`	Yes	Workspace file to generate the SBOM for.
`<output_file>`	Yes	Output file to write.
`-f`, `--format <format>`	No	Output format. Default: `cyclonedx-json`.