DFX Command Line Tool

The dfxcli tool-dfxcli/CMakeLists.txt is an example and a tool to test the API.

It can quickly send a set of pre-saved payloads to the server, or can list available studies, etc.

Operation

Description

dfxcli process

Process a bunch of payloads (alias: create measurement)

dfxcli config show

Show the active configuration

dfxcli config list

List the known configurations in dfxcloud.yaml

dfxcli login

Get a user auth-token

dfxcli logout

Release a user auth-token

dfxcli register

Get a device-token

dfxcli unregister

Release a device-token

dfxcli get study

Retrieve the studies and study config available on server

dfxcli get device

Retrieve the devices

dfxcli get user

Retrieve the users

dfxcli config sample

Write a sample configuration file to stdout

Getting started

You need to create a ~/.dfxcloud.yaml file containing common properties used while making calls and is used to initialize the CloudConfig structure.

# Note this is a "simple" format, to get advanced with multiple contexts pass
# the --advanced option.
dfxcli config sample > ~/.dfxcloud.yaml

Edit ~/.dfxcloud.yaml and provide the correct values for your environment. With a proper auth-email, auth-password, auth-org you can perform a login request to obtain a auth-token with:

dfxcli login
# Copy the auth-token value to your ~/.dfxcloud.yaml

Having an auth-token, you can place in the ~/.dfxcloud.yaml and either remove the auth-email, auth-password, auth-org or leave them there. The dfxcli first checks the CloudConfig for an auth-token and if it is unable to locate it will implicitly use the auth-email, auth-password, auth-org to obtain an auth-token for the current session. When the session ends if dfxcli performed the login, it will subsequently logout to release the token. If it was obtained from the configuration file it will remain “cached” and available for future calls.

The device-token can be handled similarly but requires a license in addition to the user authentication information and invoking:

dfxcli register
# Copy the device-token value to your ~/.dfxcloud.yaml

With a configuration file setup, using the CLI can be invoked with --help to provide more information about available options that can be customized.

Viewing configuration

# Display a list of available contexts, identifying which is the default
dfx config list

# Display the current configuration being used, append -f for full without OBFUSCATED
dfx config show

# Select a specific context 'na-rest' to use, context select can apply to all operations
dfx -c na-rest config show

Performing a measurement

# Process a folder containing payloads, it will scan for ~/payloads/payload-*.bin and
# naturally sort them then start sending them to the server with a 1 second delay which
# can be changed with the -d option.
dfxcli process ~/payloads -d 500   # 500 milliseconds

# In Bash, you can pass all the payloads using a glob expression instead of a directory.
# The payload files will still be sorted naturally unless you pass -n to not sort.
dfxcli process ~/payloads/mypayload-*bin

# Capture the server response to results.json. If you ctrl-c, it will be intercepted
# and a proper JSON file up until that point will be provided.
dfxcli process ~/payloads/*.bin --output results.json

# Verbose will include the warnings and general operation logs which are useful for
# understanding what is being sent/received from the server
dfxcli process ~/payloads/*.bin --verbose --output results.json

Other examples

# Obtaining help for tool, or operation specific help
dfxcli --help
dfxcli get --help

dfxcli config show -p    # Pretty print json output
dfxcli config show -t    # Print as table

dfxcli get study
dfxcli get device | jq -c '.[]'      # List all devices
dfxcli get device | jq -c '.[].ID'   # List just the IDs
dfxcli get device | jq -c '.[] | select(.StatusID == "ACTIVE")'  # active devices

dfxcli get user | jq -c '.[]'

# Active studies with Name and ID
dfxcli get study | jq -c '.[] | select(.StatusID == "ACTIVE") | {Name:.Name, ID:.ID}'

# If one study id given with -s option, the config will be saved
dfxcli get study -s studyConfig.bin 03da56f3-17c7-4769-ae2e-7854242bbdd8