Introduction & Summary
The recent introduction of Rivery CLI (Command-Line-Interface) has opened up a new host of programmatic workflows to run, edit, deploy and manage rivers that developers can take advantage of. The river configurations are defined by .yaml configuration files that can be edited in a simple text editor and synced with VCS tools like GitHub. In this community article, we explore the basic rivery CLI setup and some basic commands to help you get started programmatically building and deploying rivers.
The setup for the Rivery CLI is summarized as follows.
- Ensure that you have python installed at version 3.6 or higher.
- Create a python virtual environment to hold the dependencies for the Rivery CLI.
- Create an API token in your rivery account.
- Install the Rivery CLI.
- Create a New Project.
- Create a Profile.
Rivery CLI setup
1. Python Installation
The Rivery CLI is a python package built with python 3.6. On the python website, download the version compatible with your operating system and ensure that it is v3.6 or higher.
2. Create a virtual environment.
Following programmatic best practices with python, create a project directory in any location that you wish to use with the Rivery CLI. Once you have created the directory open your terminal and run the following:
python3 pip install venv
and
python3 venv -m
These will install the venv library into your base python3 installation and create a “virtual environment” in your project directory for installing the dependencies of the Rivery CLI.
Next, you want to activate the virtual environment so that any commands given will be executed from the python3 environment assigned to the project, and not your base python3 environment.
Navigate to your virtual environment folder within your project directory in the command/terminal prompt and execute:
Mac/Linux
python3 virtualenv venv
Windows
python3 Scripts/activate
to activate the virtual environment named “venv”.
3. Create a new API token.
Log in to your Rivery console and navigate to the “API tokens” tab. There, click “Add Token” and create a token with the following scopes:
- me:list
- river:execute
- river:edit
- river:list
- river:delete
- connection:edit
- connection:list
- connection:delete
Save the API token in a safe place, you will need it for step (6). You will NOT be able to view this access token again after the screen.
4. Install the Rivery CLI.
In your activated python virtual environment, using your terminal/cmd prompt, execute the following command in your activated venv:
pip install rivery-cli
and wait for the installation to finish. Confirm the installation by running:
rivery --version
If you get a response like “Rivery CLI, version ….” the installation was successful and you can move to the next step.
5. Initialize a rivery project.
Within your project directory, initialize a new rivery project by running the command:
rivery init
This will create a .yaml configuration file in your directory that you can edit.
6. Create a new profile.
In order to send the .yaml configuration that you edit/create to your rivery account, you need to create an authenticated profile(s) to hold the credentials. Rivery stores these credentials in an “entity” called profile in your project directory. The API token that you created in step (3) is unique to the account+environment that it was created from. Therefore, you will need to create a new profile for every account+environment combination that you are using. To create a profile, execute:
rivery configure
And follow the associated text prompts to create the profile (you will need the API token from step (3)).
Basic Commands
You are now ready to use the Rivery CLI to execute some basic commands onto your rivery account.
rivery rivers push
This command will take a .yaml configuration file and push it to your rivery console account into the account+environment specified by the profile parameter.
Arguments:
–paths [STRING] [Required] - This specifies the path to the .yaml file that you wish to push.
–profile [STRING] [Optional] - This specifies the profile into which you want to load the river specified in the .yaml file. If not specified, it will be the default profile.
Examples:
rivery rivers push --paths=test
rivery rivers push --paths=test/604f3221a3b1ad2c92c6419b.yaml
rivery --profile=dev rivers push --paths=test1/60570d604d2631001c84484a.yaml
rivery rivers import
This command imports a river from your rivery console to .yaml format on your desktop.
Arguments:
–path [STRING] [Required] - This specifies the path in your project directory that you want to import the .yaml files into.
–riverId [STRING] [Required] - This specifies the riverId of the river that you want to import as a .yaml. The riverId can be found in the river’s url: Rivery//river/<river_id>
–groupName [STRING] [Optional] - This specifies the Group/Kit name that you want to import as .yaml’s*
*Note that at the moment, only logic river .yaml configurations in the kit/group will be imported. Data source to target river configurations will not.
Examples:
rivery --profile=test rivers import --groupName=Test Group
rivery rivers import --groupName=Test Group --path=cli_logics
rivery rivers --profile=dev import --riverId=60570d604d2631001c84484a --path=test1
rivery rivers import --groupName=My Group --path=test1
rivery rivers run fire
This command remotely executes rivers in your rivery account within the environment where the API token for the profile was created.
Arguments:
–riverId [STRING] [Required] - This specifies the riverId of the river that you want to import as a .yaml. The riverId can be found in the river’s url: Rivery//river/<river_id>
–waitForEnd [None] [Optional] - This command polls the river continuously and returns the status until it fully executes.
–timeout [INTEGER] [Optional] - This specifies the number of seconds to poll the river until it completes (the default is two hours).
Examples:
rivery rivers run fire --riverId=605508e44cd572a6f6aba34b
rivery rivers run fire --riverId=605508e44cd572a6f6aba34b --waitForEnd
rivery rivers run fire --riverId=605508e44cd572a6f6aba34b --waitForEnd --timeout=10
rivery rivers run status
This command checks the run status of a particular river execution.
Arguments
–runId [STRING] [Required] - This specifies the runId of the execution that you want to check the status of. The runId can be found in the activities tab :
–waitForEnd [None] [Optional] - This command polls the runId continuously and returns the status until it fully executes.
–timeout [INTEGER] [Optional] - This specifies the number of seconds to poll the runid until it completes (the default is two hours).
Examples:
rivery rivers run status --runId=605508e44cd57211111111
rivery rivers run status --runId=605508e44cd57211111111 --waitForEnd
rivery rivers run status --runId=605508e44cd57211111111 --waitForEnd --timeout=10