pf

:::{admonition} Experimental feature This is an experimental feature, and may change at any time. Learn more. :::

Manage prompt flow resources with the prompt flow CLI.

Command	Description
pf flow	Manage flows.
pf connection	Manage connections.
pf run	Manage runs.
pf tool	Init or list tools.
pf config	Manage config for current user.
pf service	Manage prompt flow service.
pf upgrade	Upgrade prompt flow CLI.
pf trace	Manage traces.

pf flow

Manage promptflow flow flows.

Command	Description
pf flow init	Initialize a prompt flow directory.
pf flow test	Test the prompt flow or flow node.
pf flow validate	Validate a flow and generate `flow.tools.json` for it.
pf flow build	Build a flow for further sharing or deployment.
pf flow serve	Serve a flow as an endpoint.

pf flow init

Initialize a prompt flow directory.

pf flow init [--flow]
             [--entry]
             [--function]
             [--prompt-template]
             [--type]
             [--yes]

Examples

Create a flow folder with code, prompts and YAML specification of the flow.

pf flow init --flow <path-to-flow-direcotry>

Create an evaluation prompt flow

pf flow init --flow <path-to-flow-direcotry> --type evaluation

Create a flow in existing folder

pf flow init --flow <path-to-existing-folder> --entry <entry.py> --function <function-name> --prompt-template <path-to-prompt-template.md>

Optional Parameters

--flow

The flow name to create.

--entry

The entry file name.

--function

The function name in entry file.

--prompt-template

The prompt template parameter and assignment.

--type

The initialized flow type.
accepted value: standard, evaluation, chat

--yes --assume-yes -y

Automatic yes to all prompts; assume 'yes' as answer to all prompts and run non-interactively.

pf flow test

Test the prompt flow or flow node.

pf flow test --flow
             [--inputs]
             [--node]
             [--variant]
             [--debug]
             [--interactive]
             [--verbose]
             [--ui]

Examples

Test the flow.

pf flow test --flow <path-to-flow-directory>

Test the flow from json file.

pf flow test --flow <path-to-flow-directory> --inputs inputs.json

Test the flow with first line from jsonl file.

pf flow test --flow <path-to-flow-directory> --inputs inputs.jsonl

Test the flow with input values.

pf flow test --flow <path-to-flow-directory> --inputs data_key1=data_val1 data_key2=data_val2

Test the flow with specified variant node.

pf flow test --flow <path-to-flow-directory> --variant '${node_name.variant_name}'

Test the single node in the flow.

pf flow test --flow <path-to-flow-directory> --node <node_name>

Debug the single node in the flow.

pf flow test --flow <path-to-flow-directory> --node <node_name> --debug

Chat in the flow.

pf flow test --flow <path-to-flow-directory> --node <node_name> --interactive

Chat in the chat window.

pf flow test --flow <path-to-flow-directory> --ui

Required Parameter

--flow

The flow directory to test.

Optional Parameters

--inputs

Input data for the flow. Example: --inputs data1=data1_val data2=data2_val

--node

The node name in the flow need to be tested.

--variant

Node & variant name in format of ${node_name.variant_name}.

--debug

Debug the single node in the flow.

--interactive

Start a interactive chat session for chat flow.

--verbose

Displays the output for each step in the chat flow.

--ui

The flag to start an interactive chat experience in local chat window.

pf flow validate

Validate the prompt flow and generate a flow.tools.json under .promptflow. This file is required when using flow as a component in a Azure ML pipeline.

pf flow validate --source
                 [--debug]
                 [--verbose]

Examples

Validate the flow.

pf flow validate --source <path-to-flow>

Required Parameter

--source

The flow source to validate.

pf flow build

Build a flow for further sharing or deployment.

pf flow build --source
              --output
              --format
              [--variant]
              [--verbose]
              [--debug]

Examples

Build a flow as docker, which can be built into Docker image via docker build.

pf flow build --source <path-to-flow> --output <output-path> --format docker

Build a flow as docker with specific variant.

pf flow build --source <path-to-flow> --output <output-path> --format docker --variant '${node_name.variant_name}'

Required Parameter

--source

The flow or run source to be used.

--output

The folder to output built flow. Need to be empty or not existed.

--format

The format to build flow into

Optional Parameters

--variant

Node & variant name in format of ${node_name.variant_name}.

--verbose

Show more details for each step during build.

--debug

Show debug information during build.

pf flow serve

Serving a flow as an endpoint.

pf flow serve --source
              [--port]
              [--host]
              [--environment-variables]
              [--verbose]
              [--debug]
              [--skip-open-browser]

Examples

Serve flow as an endpoint.

pf flow serve --source <path-to-flow>

Serve flow as an endpoint with specific port and host.

pf flow serve --source <path-to-flow> --port <port> --host <host> --environment-variables key1="`${my_connection.api_key}`" key2="value2"

Required Parameter

--source

The flow or run source to be used.

Optional Parameters

--port

The port on which endpoint to run.

--host

The host of endpoint.

--environment-variables

Environment variables to set by specifying a property path and value. Example: --environment-variable key1="`${my_connection.api_key}`" key2="value2". The value reference to connection keys will be resolved to the actual value, and all environment variables specified will be set into os.environ.

--verbose

Show more details for each step during serve.

--debug

Show debug information during serve.

--skip-open-browser

Skip opening browser after serve. Store true parameter.

pf connection

Manage prompt flow connections.

Command	Description
pf connection create	Create a connection.
pf connection update	Update a connection.
pf connection show	Show details of a connection.
pf connection list	List all the connection.
pf connection delete	Delete a connection.

pf connection create

Create a connection.

pf connection create --file
                     [--name]
                     [--set]

Examples

Create a connection with YAML file.

pf connection create -f <yaml-filename>

Create a connection with YAML file with override.

pf connection create -f <yaml-filename> --set api_key="<api-key>"

Create a custom connection with .env file; note that overrides specified by --set will be ignored.

pf connection create -f .env --name <name>

Required Parameter

--file -f

Local path to the YAML file containing the prompt flow connection specification.

Optional Parameters

--name -n

Name of the connection.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

pf connection update

Update a connection.

pf connection update --name
                     [--set]

Example

Update a connection.

pf connection update -n <name> --set api_key="<api-key>"

Required Parameter

--name -n

Name of the connection.

Optional Parameter

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

pf connection show

Show details of a connection.

pf connection show --name

Required Parameter

--name -n

Name of the connection.

pf connection list

List all the connection.

pf connection list

pf connection delete

Delete a connection.

pf connection delete --name

Required Parameter

--name -n

Name of the connection.

pf run

Manage prompt flow runs.

Command	Description
pf run create	Create a run.
pf run update	Update a run metadata, including display name, description and tags.
pf run stream	Stream run logs to the console.
pf run list	List runs.
pf run show	Show details for a run.
pf run show-details	Preview a run's intput(s) and output(s).
pf run show-metrics	Print run metrics to the console.
pf run visualize	Visualize a run.
pf run archive	Archive a run.
pf run restore	Restore an archived run.

pf run create

Create a run.

pf run create [--file]
              [--flow]
              [--data]
              [--column-mapping]
              [--run]
              [--variant]
              [--stream]
              [--environment-variables]
              [--connections]
              [--set]
              [--source]
              [--resume-from] # require promptflow>=1.8.0, and original run created with promptflow>=1.8.0

Examples

Create a run with YAML file.

pf run create -f <yaml-filename>

Create a run with YAML file and replace another data in the YAML file.

pf run create -f <yaml-filename> --data <path-to-new-data-file-relative-to-yaml-file>

Create a run from flow directory and reference a run.

pf run create --flow <path-to-flow-directory> --data <path-to-data-file> --column-mapping groundtruth='${data.answer}' prediction='${run.outputs.category}' --run <run-name> --variant '${summarize_text_content.variant_0}' --stream

Create a run from an existing run record folder.

pf run create --source <path-to-run-folder>

Create a run by specifying the resume_from. (Require promptflow>=1.8.0, and original run created with promptflow>=1.8.0)

Succeeded line result of the original run will be reused, only remaining/failed lines will be run.

pf run create --resume-from <original-run-name>

pf run create --resume-from <original-run-name> --name <new-run-name> --set display_name='A new run' description='my run description' tags.Type=Test

Optional Parameters

--file -f

Local path to the YAML file containing the prompt flow run specification; can be overwritten by other parameters. Reference here for YAML schema.

--flow

Local path to the flow directory. If --file is provided, this path should be relative path to the file.

--data

Local path to the data file. If --file is provided, this path should be relative path to the file.

--column-mapping

Inputs column mapping, use ${data.xx} to refer to data columns, use ${run.inputs.xx} to refer to referenced run's data columns, and ${run.outputs.xx} to refer to run outputs columns.

--run

Referenced flow run name. For example, you can run an evaluation flow against an existing run. For example, "pf run create --flow evaluation_flow_dir --run existing_bulk_run".

--variant

Node & variant name in format of ${node_name.variant_name}.

--stream -s

Indicates whether to stream the run's logs to the console.
default value: False

--environment-variables

Environment variables to set by specifying a property path and value. Example: --environment-variable key1='${my_connection.api_key}' key2='value2'. The value reference to connection keys will be resolved to the actual value, and all environment variables specified will be set into os.environ.

--connections

Overwrite node level connections with provided value. Example: --connections node1.connection=test_llm_connection node1.deployment_name=gpt-35-turbo

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>.

--source

Local path to the existing run record folder.

pf run update

Update a run metadata, including display name, description and tags.

pf run update --name
              [--set]

Example

Update a run

pf run update -n <name> --set display_name="<display-name>" description="<description>" tags.key="value"

Required Parameter

--name -n

Name of the run.

Optional Parameter

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

pf run stream

Stream run logs to the console.

pf run stream --name

Required Parameter

--name -n

Name of the run.

pf run list

List runs.

pf run list [--all-results]
            [--archived-only]
            [--include-archived]
            [--max-results]

Optional Parameters

--all-results

Returns all results.
default value: False

--archived-only

List archived runs only.
default value: False

--include-archived

List archived runs and active runs.
default value: False

--max-results -r

Max number of results to return. Default is 50.
default value: 50

pf run show

Show details for a run.

pf run show --name

Required Parameter

--name -n

Name of the run.

pf run show-details

Preview a run's input(s) and output(s).

pf run show-details --name

Required Parameter

--name -n

Name of the run.

pf run show-metrics

Print run metrics to the console.

pf run show-metrics --name

Required Parameter

--name -n

Name of the run.

pf run visualize

Visualize a run in the browser.

pf run visualize --names

Required Parameter

--names -n

Name of the runs, comma separated.

pf run archive

Archive a run.

pf run archive --name

Required Parameter

--name -n

Name of the run.

pf run restore

Restore an archived run.

pf run restore --name

Required Parameter

--name -n

Name of the run.

pf tool

Manage promptflow tools.

Command	Description
pf tool init	Initialize a tool directory.
pf tool list	List all tools in the environment.
pf tool validate	Validate tools.

pf tool init

Initialize a tool directory.

pf tool init [--package]
             [--tool]
             [--set]

Examples

Creating a package tool from scratch.

pf tool init --package <package-name> --tool <tool-name>

Creating a package tool with extra info.

pf tool init --package <package-name> --tool <tool-name> --set icon=<icon-path> category=<tool-category> tags="{'<key>': '<value>'}"

Creating a package tool from scratch.

pf tool init --package <package-name> --tool <tool-name>

Creating a python tool from scratch.

pf tool init --tool <tool-name>

Optional Parameters

--package

The package name to create.

--tool

The tool name to create.

--set

Set extra information about the tool, like category, icon and tags. Example: --set =.

pf tool list

List all tools in the environment.

pf tool list [--flow]

Examples

List all package tool in the environment.

pf tool list

List all package tool and code tool in the flow.

pf tool list --flow <path-to-flow-direcotry>

Optional Parameters

--flow

The flow directory.

pf tool validate

Validate tool.

pf tool validate --source

Examples

Validate single function tool.

pf tool validate -–source <package-name>.<module-name>.<tool-function>

Validate all tool in a package tool.

pf tool validate -–source <package-name>

Validate tools in a python script.

pf tool validate --source <path-to-tool-script>

Required Parameter

--source

The tool source to be used.

pf config

Manage config for current user.

Command	Description
pf config set	Set prompt flow configs for current user.
pf config show	Show prompt flow configs for current user.

pf config set

Set prompt flow configs for current user, configs will be stored at ~/.promptflow/pf.yaml.

pf config set

Examples

Config connection provider to azure workspace for current user.

pf config set connection.provider="azureml://subscriptions/<your-subscription>/resourceGroups/<your-resourcegroup>/providers/Microsoft.MachineLearningServices/workspaces/<your-workspace>"

pf config show

Show prompt flow configs for current user.

pf config show

Examples

Show prompt flow for current user.

pf config show

pf service

Manage prompt flow service.

Command	Description
pf service start	Start prompt flow service.
pf service stop	Stop prompt flow service.
pf service status	Display the started prompt flow service info.

pf service start

Start the prompt flow service.

pf service start [--port]
                 [--force]
                 [--debug]

Examples

Prompt flow will try to start the service on the default port 23333. If the port is already taken, prompt flow will sequentially probe new ports, incrementing by one each time. Prompt flow retains the port number for future reference and will utilize it for subsequent service startups.

pf service start

Forcefully start the prompt flow service. If the port is already in use, the existing service will be terminated and restart a new service

pf service start --force

Start the prompt flow service with a specified port. If the port is already taken, prompt flow will raise an error unless forcefully start the service with the --force flag. Upon availability, prompt flow retains the port number for future reference and will utilize it for subsequent service startups.

pf service start --port 65553

Start prompt flow service in foreground, displaying debug level logs directly in the terminal.

pf service start --debug

Optional Parameters

--port -p

The designated port of the prompt flow service and port number will be remembered if port is available.

--force

Force restart the existing service if the port is used.

--debug

Start prompt flow service in foreground, displaying debug level logs directly in the terminal.

pf service stop

Stop prompt flow service.

pf service stop [--debug]

Example

Stop prompt flow service.

pf service stop

Optional Parameter

--debug

The flag to turn on debug mode for cli.

pf service status

Display the started prompt flow service info.

pf service status

pf upgrade

Upgrade prompt flow CLI.

Command	Description
pf upgrade	Upgrade prompt flow CLI.

Examples

Upgrade prompt flow without prompt and run non-interactively.

pf upgrade --yes

pf trace

Manage prompt flow traces.

Command	Description
pf trace delete	Delete traces

pf trace delete

Delete traces.

pf trace delete [--run]
                [--collection]
                [--started-before]  # should combine with `collection`

Examples

Delete traces comes from a specific run.

pf trace delete --run <run-name>

Delete traces in a specific collection.

pf trace delete --collection <collection>

Delete traces in a specific collection started before a specific time.

# `started-before` should be in ISO 8601 format
pf trace delete --collection <collection> --started-before '2024-03-19T15:17:23.807563'

Autocomplete

To activate autocomplete features for the pf CLI you need to add the following snippet to your ~/.bashrc or ~/.zshrc:

source <promptflow_package_install_root>/pf.completion.sh

Files

pf-command-reference.md

Latest commit

History

pf-command-reference.md

File metadata and controls

pf

pf flow

pf flow init

Examples

Optional Parameters

pf flow test

Examples

Required Parameter

Optional Parameters

pf flow validate

Examples

Required Parameter

pf flow build

Examples

Required Parameter

Optional Parameters

pf flow serve

Examples

Required Parameter

Optional Parameters

pf connection

pf connection create

Examples

Required Parameter

Optional Parameters

pf connection update

Example

Required Parameter

Optional Parameter

pf connection show

Required Parameter

pf connection list

pf connection delete

Required Parameter

pf run

pf run create

Examples

Optional Parameters

pf run update

Example

Required Parameter

Optional Parameter

pf run stream

Required Parameter

pf run list

Optional Parameters

pf run show

Required Parameter

pf run show-details

Required Parameter

pf run show-metrics

Required Parameter

pf run visualize

Required Parameter

pf run archive

Required Parameter

pf run restore

Required Parameter

pf tool

pf tool init

Examples

Optional Parameters

pf tool list

Examples

Optional Parameters

pf tool validate

Examples

Required Parameter

pf config

pf config set

Examples

pf config show

Examples

pf service