Tasks

The CLI can list and run tasks from a generated CFS workspace. Task discovery combines the platform tasks generated for each project with any custom tasks defined in .vscode/cfs.tasks.json.

Important

Task commands operate on a generated workspace directory that contains a .cfs folder.

• For cfsutil tasks list, pass the workspace root with --workspace, or run the command from a project directory inside that workspace.
• For cfsutil tasks run, pass the workspace root with --workspace and the project directory with --project, or run the command from that project directory.
• Do not pass the source .cfsworkspace file to these commands.

When running tasks that flash and run an application on a board, the --capture and --port switches can be used to capture output from a serial port. The output will be echoed to the terminal window. The CLI will continue to capture output until halted by CTRL+C. For more information on viewing active serial ports, see cfsutil port list.

The CLI will detect when a Zephyr application emits CTF tracing and will direct all subsequent output to a CTF file. When trace capture is halted with CTRL+C, the CLI will automatically generate a TEF ("Trace Event Format") file from this file.

List tasks

cfsutil tasks list [-w <workspace-path>] [-p <project-name>] [-v]

Lists the tasks available in a generated workspace.

Flag	Description
-w, --workspace=<path>	Workspace root to inspect. Defaults to the current directory. The directory must either contain .cfs, or be a project directory inside a workspace that contains .cfs.
-p, --project=<name>	Optional project folder name to filter the output.
-v, --verbose	Also display the command associated with each task.

Example

cfsutil tasks list -w /home/<username>/analog/cfs/2.3.0/MyWorkspace
cfsutil tasks list -w /home/<username>/analog/cfs/2.3.0/MyWorkspace -p m4 -v
cd /home/<username>/analog/cfs/2.3.0/MyWorkspace/m4
cfsutil tasks list

Note

The list output is grouped by project and shown in alphabetical order. The displayed task name is a command-line-friendly rendering of the task label.

Run a task

cfsutil tasks run <task> [-w <value>] [-p <project-name>] [-v] [--capture --port <value>] [-z <value>]

Runs a task from a project inside a generated workspace.

Argument / Flag	Description
<task>	Task to run. Use the task names listed in tasks list.
-c, --capture	Capture serial port output after task execution. Capturing will continue until the process is terminated. Used with --port and --project.
-p, --project=<value>	Project folder name, relative to the workspace root. Identifies which project's task to run.
-v, --verbose	Enable verbose output.
-w, --workspace=<value>	The workspace path used for task discovery. Defaults to the current directory.
-z, --zephyrTraceFile=<value>	TEF (Trace Event Format) output file path for Zephyr tracing. The CLI captures raw CTF data to an intermediate file and generates the TEF file when capture is stopped. Used with --capture.
--port=<value>	Specify the serial port name (e.g., COM3, /dev/ttyUSB0). Used with --capture.

Example

cfsutil tasks run build -w /home/<username>/analog/cfs/2.3.0/MyWorkspace -p m4
cfsutil tasks run flash_run_JLink -w /home/<username>/analog/cfs/2.3.0/MyWorkspace -p m4 --capture --port COM4
cd /home/<username>/analog/cfs/2.3.0/MyWorkspace/m4
cfsutil tasks run build

Note

cfsutil tasks run only accepts sanitized task names printed by cfsutil tasks list.

Define tasks for CLI use

Custom CLI tasks must be defined in the project file .vscode/cfs.tasks.json.

Use the same project directory layout generated by CodeFusion Studio:

<workspace-root>/
    .cfs/
    <project-name>/
        .vscode/
            cfs.tasks.json
            settings.json

Minimal example:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "type": "shell",
            "command": "make -j8",
            "options": {
                "cwd": "${workspaceFolder}",
                "env": {
                    "EXTRA_INCLUDE": "${config:cfs.sdk.path}/SDK/Libraries"
                }
            }
        }
    ]
}

Authoring guidance

• Define custom tasks in .vscode/cfs.tasks.json under each project.
• Keep task label values simple and shell-friendly. The CLI resolves tasks by label.
• Use options.cwd when the command must run from a specific project directory.
• Use options.env for task-specific environment variables.
• Use cfs.environment in .vscode/settings.json for environment variables that should apply to every task in the project. Variable references such as ${config:...} are resolved before injection.
• Use linux, windows, and osx overrides when the command or options differ by platform.
• Keep .vscode/settings.json in the same project if your task uses ${config:...} variables.
• Treat .vscode/settings.json as the source of truth for CLI task settings. Changes made in the VS Code Settings UI are not written back automatically for CLI use unless the setting is explicitly stored in that file.
• If you need a setting key or JSON snippet, use VS Code's Copy Setting ID or Copy Setting as JSON, then paste the result into the project's .vscode/settings.json and set the value manually.

Settings, environment, and path resolution

The CLI resolves task settings from these sources, with later sources overriding earlier ones:

1. Built-in CFS setting defaults packaged inside cfsutil
2. User config.json settings
3. Workspace .code-workspace settings (when running within a workspace file)
4. Project .vscode/settings.json (when running tasks within a workspace folder)

Configuration file location

The CLI reads configuration from config.json. The installer creates this file automatically at:

Platform	Default Location
Linux/macOS	~/.config/cfsutil/config.json
Windows	%LOCALAPPDATA%\cfsutil\config.json

The default file contains:

{
  "cfs.jlink.path": ""
}

The installer only creates this file if it doesn't already exist, preserving any modifications you have made.

J-Link path required for erase tasks

J-Link erase tasks (erase_JLink) require the cfs.jlink.path setting to be configured. Set cfs.jlink.path to your J-Link installation directory (for example, /opt/SEGGER/JLink_<version> on Linux, /Applications/SEGGER/JLink_<version> on macOS, or C:\Program Files\SEGGER\JLink_<version> on Windows). This requirement exists because the erase command invokes JLinkExe directly rather than going through west, and therefore cannot automatically resolve the J-Link executable path. For detailed installation and configuration instructions, see Install Segger J-Link debugger drivers.

You can override the default location using environment variables:

• CFSUTIL_CONFIG_HOME – overrides the config directory path
• XDG_CONFIG_HOME – (Linux only) follows XDG base directory spec

Custom config location

If CFSUTIL_CONFIG_HOME is set to c:/cygwin64/home/<username>/config, the config file will be c:/cygwin64/home/<username>/config/cfsutil/config.json.

To customize CLI behavior, edit config.json in a text editor. The file uses JSON format and supports the configuration options shown in the example below.

Example configuration

{
    "cfsInstallPath": "/home/<username>/analog/cfs/2.3.0",
    "toolSearchPaths": ["/opt/toolchains/arm-gnu-toolchain/bin"],
    "env": {
        "ARM_GCC_DIR": "/opt/toolchains/arm-gnu-toolchain/bin",
        "PATH": "/opt/toolchains/arm-gnu-toolchain/bin"
    }
}

Use these fields as follows:

• cfsInstallPath: Fallback path to the CFS installation directory (must contain cfs.json). Used when CFS_INSTALL_DIR environment variable and cfs.sdk.path are not set. Setting this avoids expensive directory traversal during startup.
• toolSearchPaths: CLI-wide custom directories used for tool discovery.
• env: CLI-wide environment variables added to every task execution.

For end users, prefer project-local values in .vscode/settings.json whenever a setting is required to resolve a task consistently for that project. Use config.json for machine-wide overrides that should apply across multiple workspaces.

Project-level environment variables

Use the cfs.environment key in .vscode/settings.json to define environment variables that apply to every task in that project. This is equivalent to adding options.env to each task individually, but maintained in a single place.

{
    "cfs.environment": {
        "TOOLCHAIN_VER": "RJ-2025.5-linux",
        "XTENSA_TOOLCHAIN_PATH": "/opt/toolchains/xtensa",
        "XTENSA_CORE": "${config:cfs.xtensa.core}",
        "ZEPHYR_BASE": "${command:cfs.tool.path.zephyr}",
        "WORKSPACE_OUT": "${workspaceFolder}/build"
    }
}

Variable references are resolved before the variables are injected into the task process environment. All variable families supported in task commands are also supported here: ${config:...}, ${env:...}, ${command:...}, ${workspaceFolder}, ${cfs:...}, and the predefined variables listed in Supported variables in CLI tasks.

When the same key is defined in both cfs.environment and a task's options.env, the task-level value wins.

Supported variables in CLI tasks

The CLI resolves these variable families in cfs.tasks.json:

• ${config:<key>} from merged CFS settings.
• ${env:<name>} from the current shell environment.
• ${command:<name>} for supported CFS commands such as tool path lookups.
• ${workspaceFolder} from the current project directory used to run the task.
• ${workspaceFolderBasename}, ${userHome}, ${pathSeparator}, and ${/}.
• ${cfs:...} values handled by the shared CFS variable resolver.

The CLI does not provide editor-only VS Code variables such as ${file}, ${relativeFile}, ${lineNumber}, or ${selectedText}.

PATH handling during task execution

Task execution starts from the composed CFS shell environment, which already includes discovered tool paths and SDK-related paths. Then the CLI applies additional environment variables from the task definition and from config.json.

If either the task or config.json defines PATH, that value is prepended to the composed PATH instead of replacing it. This keeps required CFS toolchain paths available while still letting you add custom tool directories.