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