Eventline is now open source and available on GitHub !

If you are still using the old Eventline platform, contact us to migrate to the new service, and head to the new documentation website for more information.

evcli

Introduction

The evcli program interacts with the Eventline platform. It can be used to retrieve information about various components, manage projects, control pipelines…

Installation

The fastest way to install evcli is to use the installation script:

curl -sSLf https://download.eventline.net/evcli-install | sh -

The script will detect the appropriate binary depending on your operating system and system architecture, and will install it to /usr/local/bin/evcli.

You can also directly download the last release published from GitHub. Take care to select the right binary depending on your operating system and system architecture.

Updates

The evcli program can update itself. Simply run evcli update! If a new version is available, it will be downloaded and installed at the same path as the current version.

Conventions

Status

All commands exit with a status code equal to zero if they succeed. On failure, a non-zero status code is used. The status code 1 is the only error status code used for the time being.

Output

Commands write the output of their main operation to the standard output. All other content is written to the standard error output; this includes all kinds of messages and data table headers.

As a result, the output of evcli can always be processed by various tools: you can simply pipe evcli commands into other programs without having to filter out any non-relevant content.

Information

Commands usually do not display any status or information message when they succeed, in accordance with the UNIX Rule of Silence.

The --verbose global option can be used to enable informational messages.

Configuration

Configuration is stored in a regular file at $HOME/.config/evcli/config.json. If the file does not exist, evcli will create it and fill it with the default configuration.

Note that the configuration file will store your API key. If you write the configuration file yourself, make sure to set permissions to 0600. Evcli checks for permissions at startup and aborts if the configuration file is readable for anyone but the file owner.

Settings

Settings are stored hierarchically. For example, for api.endpoint, the endpoint member is stored in an api top-level JSON object.

The following settings are available:

api.endpoint
The base URI of the Eventline API server. This setting should not be modified.
api.key
The API key used by evcli to authenticate on the API server.
interface.color
Whether to activate color in the output of evcli or not. This setting is overridden by the --color option.
misc.disable_update_check
If true, do not check for evcli updates at startup.

The show-config, get-config and set-config commands can be used to interact with the current configuration.

Options

Global options

The following options can be used with all commands:

--debug <level>
enable debug messages of level <level> or higher. The level is a positive integer; higher log levels are used for more detailed debug messages.
-h, --help
Print information about a command, its options and its arguments.
--no-color
Do not use any color in the output.
-v, --verbose
Enable status and information messages.
-y, --yes
Skip all confirmation prompts, automatically using “yes” as response.

Project selection options

Most commands are executed in the context of a specific Eventline project. Evcli will try to obtain the project id using several methods:

  • First, if one of the --project-id and --project-name options is provided, evcli will use it.
  • Then if one of the EVENTLINE_PROJECT_ID and EVENT_PROJECT_NAME environment variables is defined, evcli will use it.
  • Finally, evcli will look for a project file, eventline-project.json in the current directory, and use it to identify the current project.

The project detection process is skipped for commands which do not depend on a current project.

Info

Eventline will always set EVENTLINE_PROJECT_ID and EVENTLINE_PROJECT_NAME when executing tasks. As a result, executing evcli in an Eventline task without providing --project-id or --project-name will automatically select the current project.

This does not affect project commands such as deploy-project which skip the project detection process and rely on explicit parameters instead.

Resource files

File selection

Commands such as deploy-project operate on a set of resource files. Evcli locates resource files by recursively searching for all YAML files in the project directory.

Evcli will only select files with either the .yaml or .yml extension. It will ignore hidden files, files located in hidden directories, and files matching the content of the .evcli-ignore file.

Info
You can use the list-project-files command to print the list of the files selected by evcli. You can also add the --debug 2 global option to know which files were ignored by evcli and why.

Ignore file

The ignore file is used to provide a list of directories of files which should not be used by evcli to discover resource files. The file must be named .evcli-ignore and be located at the root of the project, at the same level as the eventline-project.json file.

The ignore file contains a list of patterns. Empty lines and lines starting with a ‘#’ character are ignored. Each pattern matches a file or directory to be ignored by evcli. Patterns ending with ‘/’ designate directories. For example, foo.yaml will match all foo.yaml files; foo/ will match all files located in directories named foo.

A pattern starting with / will only match at the root of the project. For example, /foo.yaml will only match a foo.yaml file located at the root of the project, while foo.yaml will match any foo.yaml file in all sub-directories.

Finally the following special characters are supported:

  • ? matches any character.
  • * matches any sequence of characters other than /.
  • ** matches any sequence of characters including /.

For example, the following ignore file means that evcli will skip:

  • the doc directory at the root of the project;
  • any node_modules directory;
  • any YAML file starting with test-.
node_modules/
/doc/
test-*.yaml

Commands

The following section contains descriptions of all available commands. Use the help command for more information about the arguments and options of each command.

help

Print information about the commands and options available for evcli.

The help command can be called with the name of a command as argument. In that case, evcli will print information about this command.

Example:

evcli help create-project

version

Print the version of the evcli program.

show-config

Print the current configuration as a JSON value. If the --entries option is set, print a table containing the value of all settings.

get-config

Extract and print the value of a setting.

Example:

evcli get-config api.endpoint

set-config

Change the value of a setting.

Example:

evcli set-config interface.color true

list-projects

Print a list of all projects in the organization.

create-project

Create a new project. The name of the project and the directory which will contain the resource files must be passed as arguments.

Example:

evcli create-project ops .

delete-project

Delete a project and all resources and identities it contains. This command will ask for confirmation unless the --yes global option is set.

Warning
Project deletion cannot be reversed.

deploy-project

Deploy a project using the resource files in a project directory. The project directory is by the default the current one; the --directory option can be used to specify another directory.

See the resource files documentation for more information.

list-project-files

Print a list of all resource files in a project directory. The path of each file is relative to the project directory.

list-commands

List all commands defined in the current project.

describe-command

Describe a command in the current project, printing its name, description and parameters.

execute-command

Execute a command. The name of the command is passed as first arguments. Additional arguments can be used to set command parameters.

Each parameter is passed as a <name>=<value> argument.

Example:

evcli execute-command create-feature-env name=client-demo branch=experimental public=true

The command prints the identifier of the command execution.

list-pipelines

List the last instantiated pipelines in the current project.

abort-pipeline

Abort a pipeline either while it is running or before it has started. The identifier of the pipeline must be passed as argument. Pipeline identifiers can be obtained using the list-pipelines command.

restart-pipeline

Restart a pipeline after it has finished. The identifier of the pipeline must be passed as argument. Pipeline identifiers can be obtained using the list-pipelines command.

show-scratchpad

Fetch all entries in a scratchpad and print them.

clear-scratchpad

Delete all entries in a scratchpad.

get-scratchpad-entry

Fetch a single entry in a scratchpad and print it.

set-scratchpad-entry

Set or update the value of an entry in a scratchpad.

delete-scratchpad-entry

Delete a single entry in a scratchpad.

create-event

Create a new custom event. The arguments are the connector (only custom is supported for the time being), the name of the event, and the data stored in the event as a JSON object.

Example:

evcli create-event -t 2021-08-30T17:25:00Z custom my-event '{"a":1}'

Note that the data argument can be set to the - string; evcli will then read data from the standard input. For example, with jo:

Example:

jo a=1 | evcli create-event -t 2021-08-30T17:25:00Z custom my-event -

replay-event

Replay an event. The argument is the identifier of the event to replay.

The command prints the identifier of the event which was created.