Installation of the Command-Line Client¶
RAW includes a command-line client (CLI) that allows the execution of queries and other operations on a RAW server from the shell.
Please go to the RAW frontend downloads web page by clicking: Settings >> Install.
there click on the download link for your corresponding operative system (Windows, Linux or MacOS).
To install open a terminal where you downloaded the file and run the following command:
$ pip3 install <downloaded file> --user
For usage instructions, run
Alternatively, it is possible to use virtualenv to install the client in an isolated environment, e.g:
$ virtualenv rawcli $ source rawcli/bin/activate $ pip3 install <downloaded file>
rawcli tool will look for a configuration called
raw.ini in the following locations in order:
<user home directory>/.raw.ini
Alternatively, it is possible to specify a configuration file by using the -c option.
$ rawcli -c <config> ...
The following is an example of a simple configuration, where the RAW server is running on localhost in unsafe mode:
[raw] executor_url = http://localhost:54321 creds_url = http://localhost:54322 auth = basic disable_tls_cert_verification = false [auth_basic] access_token = token
If using a TLS connection (e.g., when the connection between the client and the RAW services
is proxied using TLS), it is possible to disable verification of the TLS certificate by setting
This is useful in cases where the system is using self-signed certificates or certificates that were
issued with a different name than the endpoint used to access the RAW servers.
If RAW is using Auth0 for user management and authentication, use the following configuration (the missing values will be provided).
[raw] executor_url = <EXECUTOR-ADDRESS> creds_url = <CREDS-SERVER-ADDRESS> auth = auth0 [auth0] domain = raw.eu.auth0.com audience = https://just-ask.raw-labs.com auth_type = client_credentials client_id = <AUTH0 CLIENT ID> client_secret = <AUTH0 CLIENT SECRET>
Before calling the RAW, the RAW clients needs to obtain a valid OAuth access token. The access token is obtained directly from the Authentication Provider (e.g. Auth0) and then stored locally in disk. This token will then be used by the ARW client to authenticate the user with RAW.
There are two ways to obtain the access token: interactive and non-interactive login. The following sections describe each mechanism. You can obtain ready-to-use configuration files for either of the authentication mechanisms by going to the Frontend -> Settings -> Authentication page.
This should be preferred when the client is running on a machine with a browser.
The user must first run
rawcli login to launch a browser and authenticate directly with the OAuth2 provider
(using the Authorization Code OAuth2 flow).
The OAuth2 provider will respond with an access token with a limited validity (e.g. 24h).
Once the validity is expired, the user can run
rawcli login again to obtain a new token.
Here is an example of a Python client configuration file set to use interactive login:
[auth_oauth2] provider = auth0 domain = raw.eu.auth0.com audience = http://just-ask.raw-labs.com grant_type = authorization_code client_id = <AUTH0 CLIENT ID> client_secret = <AUTH0 CLIENT SECRET>
This configuration is for services that use RAW non-interactively. It uses the client credentials authentication flow of OAuth2.
Contrary to the configuration for interactive clients, this process does not require any intervention from the user (namely, no browser-based authentication) so it is suitable for batch jobs.
[auth_oauth2] provider = auth0 domain = raw.eu.auth0.com audience = http://just-ask.raw-labs.com grant_type = client_credentials client_id = <AUTH0 CLIENT ID> client_secret = <AUTH0 CLIENT SECRET>