Documentation

cavctl

The cavctl binary is a standalone command-line tool (CLI) to manage Cavaliba systems remotely. It is is a golang thin wrapper around the Cavaliba API, built with cobra/viper librairies.

Setup overview

Select the appropriate binary from the cavaliba download page
Create an API Key in your Cavaliba instance with appropriate permissions (eg. p_info)
Optionnaly, create a ~/cavaliba/cavctl.yaml configuration file
run cavctl from your shell

Build

You can build your own cavctl binary if your specific binary is not available. Setup GOLANG on your system and download the latest cavaliba dsitribution.

Use the make build from the cavaliba/cavctl/ source directory. The resulting binary is in the build/ subfolder.

You can copy/install this binary on other machines with the same OS/ARCH. See GOLANG cross compilation for details.

Help flag

help

$ ./cavctl/bin/cavctl --help
cavctl is a CLI standalone command to manage remote Cavaliba systems

Usage:
  cavctl [flags]
  cavctl [command]

Available Commands:
  asset       displays asset information
  group       displays group information
  help        Help about any command
  import      Import data into a Cavaliba instance
  info        display information about a Cavaliba instance
  permission  displays permission information
  ping        ping remote cavaliba instance
  pipeline    list or run a pipeline
  role        displays role information
  schema      display schema information from Cavaliba instance
  task        displays task information
  user        displays user information
  version     displays remote cavaliba version

Flags:
      --client_id string       API Client ID
      --client_secret string   API Client Secret
      --conf string            config file (default is $HOME/.cavaliba/default.yaml)
      --delimiter string       CSV delimiter (default ",")
      --expand                 Expand result
      --file string            File path for import/export operations
  -f, --format string          Output format : json, yaml, txt (default "json")
  -h, --help                   help for cavctl
      --id int                 ID filter
      --key string             Key filter
      --outfile string         Append results to file instead of stdout
      --page int               Page number
      --pipeline string        Pipeline name for data transformation
      --refs string            Refs filter
      --rev int                Number of revisions to include
      --schema string          Schema filter
      --search string          Search filter
      --size int               Page size
      --ssl_skipverify         skip TLS/SSL cert verification
      --timeout int            API timeout (msec) (default 7000)
      --url string             Cavaliba Root URL (default "http://localhost:8000/api/")
  -v, --verbose                verbose output

Use "cavctl [command] --help" for more information about a command.

Empty command

Retrieves the cavctl version.

$ cavctl
cavctl version: 1.8.0

Explicit command-line parameters

In order to query a cavaliba system, you need to define the API endpoint :

$ cavctl version --url http://127.0.0.1:8000/ --client_id key1 --client_secret goodsecret
{
    "version": "3.27.3"
}

You can check the status code with the -v option (verbose):

$ cavctl version --url http://127.0.0.1:8000/ --client_id key1 --client_secret wrongsecret -v
(...)
status:     401
(...)

A 401 status code is an unauthorized response.

Use a config file

To save typing, use a config file.

$ cavctl --config myconfig.yaml

By default, cavctl will try $HOME/.cavaliba/cavctl.yaml which you should populate with your regular parameters.

Example:

url: http://localhost/
client_id: key1
client_secret: xxxxxxxxxxxxx
timeout: 5000
ssl_skipverify: false

Verbose flag

Use -v option to display more informations, such as config file, API URL, duration, response code, etc.

$ cavctl version -v
----- Configuration -----
Configuration:   /home/cavaliba/.cavaliba/cavctl.yaml
url:             http://localhost:8000/api/
timeout:         2000
client_id:       test
ssl_skipverify:  true

----- API Request -----
API:        http://localhost:8000/api/version/

----- API Response -----
status:     200
duration:   44.22706ms

----- DATA -------------
{
  "version": "3.27.2"
}

outfile

New: v1.8.0

Append all command output to a file instead of stdout. The file is created if it does not exist; new results are appended.

# Append results to a file
cavctl asset --schema site --outfile /tmp/sites.json

# Collect multiple commands into the same file
cavctl user --outfile results.json
cavctl group --outfile results.json

ssl_skipverify

Version: 1.1.0

Ignore Cavaliba URL TLS/SSL Cerificate check (duration, issuer, fqdn).

Default: false

Usage:

# CLI
cavctl --ssl_skipverify

# envvar
export CAVALIBA_SSL_SKIPVERIFY=true && cavctl -v
ssl_skipverify: true


# persist in cavaliba.yaml:
ssl_skipverify: true

Commands

ping

It can be used to manage a Load-Balancer and check connectivity to a remote Cavaliba system.

Permission required: None

cavctl ping
{
  "status": "OK"
}

version

This command calls the configured cavaliba instance and retrieves it’s version. Issues a warning if CLI local binary cavctl version can be updated.

Permission required: p_info

$ cavctl version
{
    "version": "3.21.0"
    "cavctl_supported_version": "1.7.0"
}

user

Retrieves user information from the remote Cavaliba instance.

Permission required: p_user_read

$ cavctl user
$ cavctl user --id 1
$ cavctl user --key patricia
$ cavctl user --search admi
$ cavctl user --page 3 --size 5 --format json

Example:

$ cavctl user --key adela81
{
  "classname": "_user",
  "login": "adela81",
  "external_id": "BA-948192",
  "email": "Torrecilla@demo.cavaliba",
  "mobile": "+56-16832089",
  "firstname": "Marijn",
  "lastname": "Torrecilla",
  "displayname": "Marijn Torrecilla",
  "is_enabled": true,
  "want_notifications": true,
  "want_email": true
}

permission

New: v3.32.0

Retrieves permission information from the remote Cavaliba instance. Alias: permissions.

Permission required: p_permission_read

$ cavctl permission
$ cavctl permission --id 42
$ cavctl permission --key p_data_admin
$ cavctl permission --search data
$ cavctl permission --page 1 --size 10 --format yaml

Example:

$ cavctl permission --key p_data_admin
{
  "classname": "_permission",
  "keyname": "p_data_admin",
  "displayname": "Data Admin",
  "is_enabled": true,
  "is_builtin": true
}

schema

Retrieves schema information from the remote Cavaliba instance. Alias: schemas.

Permission required: p_schema_read

Without --schema, returns the list of all schemas. With --schema, returns the full field definition of a single schema.

Flags	Endpoint
(none)	`schemas/` — all schemas
`--schema`	`schemas/<schema>/` — single schema with fields

Additional options: --format.

$ cavctl schema
$ cavctl schema --schema site
$ cavctl schema --schema site --format yaml

Example:

$ cavctl schema --schema site
{
  "classname": "_schema",
  "keyname": "site",
  "displayname": "Sites",
  "is_enabled": true,
  "_options": {
    "icon": "fa-hospital-o",
    "p_read": "p_data_site_read",
    "p_create": "p_data_site_create",
    "p_update": "p_data_site_update",
    "p_delete": "p_data_site_delete"
  },
  "country": {
    "displayname": "Country code",
    "dataformat": "string",
    "order": 104
  },
  "zip": {
    "displayname": "ZipCode",
    "dataformat": "string",
    "order": 106
  }
}

asset

Retrieves asset (instance) information from the remote Cavaliba instance. Aliases: assets, instance, instances.

Permission required: per schema (e.g. p_data_<schema>_read)

The endpoint is selected based on the flags provided:

Flags	Endpoint
(none)	`assets/` — all assets
`--id`	`assets/<id>/`
`--schema`	`assets/<schema>/` — all instances of a schema
`--schema` + `--key`	`assets/<schema>/<key>/` — single instance

Additional options: --search, --page, --size, --format, --expand, --refs, --rev.

$ cavctl asset
$ cavctl asset --id 35
$ cavctl asset --schema site
$ cavctl asset --schema site --search anc
$ cavctl asset --schema site --key GAVLE
$ cavctl asset --schema site --search anc --format yaml --page 2 --size 5
$ cavctl asset --schema site --key GAVLE --expand
$ cavctl asset --schema test --id 968 --refs '_user,*'
$ cavctl asset --schema site --key GAVLE --rev 5
$ cavctl asset --schema site --key GAVLE --rev 10 --refs '*'

Example:

$ cavctl asset --schema site --key GAVLE
{
  "id": 42,
  "classname": "site",
  "keyname": "GAVLE",
  "displayname": "Gavle Rehabilitation Center",
  "country": "SE",
  "zip": "80256"
}

group

New: v3.32.0

Retrieves group information from the remote Cavaliba instance.

Permission required: p_group_read

$ cavctl group
$ cavctl group --id 42
$ cavctl group --key g_cloud_engineer
$ cavctl group --search cloud
$ cavctl group --page 1 --size 10 --format yaml

Example:

$ cavctl group --key g_cloud_engineer
{
  "classname": "_group",
  "keyname": "g_cloud_engineer",
  "displayname": "Cloud Engineers",
  "is_enabled": true,
  "subgroups": [],
  "users": [
    "alice",
    "bob"
  ]
}

role

New: v3.32.0

Retrieves role information from the remote Cavaliba instance.

Permission required: p_role_read

$ cavctl role
$ cavctl role --id 42
$ cavctl role --key role_admin
$ cavctl role --search api
$ cavctl role --page 1 --size 10 --format yaml

Example:

$ cavctl role --key role_admin
{
  "classname": "_role",
  "keyname": "role_admin",
  "displayname": "Administrators",
  "is_enabled": true,
  "subgroups": [],
  "users": [
    "admin"
  ],
  "permissions": [
    "p_admin",
    "p_data_admin",
    "p_user_admin"
  ]
}

task

New: v1.8.0

Retrieves asynchronous task information from the remote Cavaliba instance. Alias: tasks.

Permission required: p_info

Without --key, returns the list of tasks. With --key <uuid>, returns the detail of a single task. Use --stop to abort a running task.

Flags	Description
(none)	List all tasks
`--key <uuid>`	Task detail
`--key <uuid> --stop`	Stop (abort) a running task
`--state <state>`	Filter by state: `QUEUED`, `RUNNING`, `DONE`, `FAILED`, `ABORTED`

$ cavctl task
$ cavctl task --state RUNNING
$ cavctl task --key 550e8400-e29b-41d4-a716-446655440000
$ cavctl task --key 550e8400-e29b-41d4-a716-446655440000 --stop

Example:

$ cavctl task --key 550e8400-e29b-41d4-a716-446655440000
{
  "handle": "550e8400-e29b-41d4-a716-446655440000",
  "state": "DONE",
  "name": "pipeline_run",
  "progress": {
    "percent": 100,
    "count": 42,
    "total": 42
  },
  "output": {
    "count_ok": 40,
    "count_ko": 2
  }
}

pipeline

New: v1.8.0

Lists available pipelines or runs a pipeline on one or more schemas. Alias: pipelines.

Permission required: p_pipeline_run (to run a pipeline) and optionally a per-pipeline defined run_permission.

Without --key, returns the list of pipelines. With --key <name> and --schema <schemas>, submits a pipeline run as an async task and polls for completion.

Flags	Description
(none)	List all pipelines
`--key <name>` + `--schema <s1,s2>`	Run pipeline on the given schemas
`--dryrun`	Run in dry-run mode (no changes applied)
`--no-wait`	Submit and return immediately (no polling)
`--interval <sec>`	Poll interval in seconds (default 2)

$ cavctl pipeline
$ cavctl pipeline --key mypipeline --schema site
$ cavctl pipeline --key mypipeline --schema site,server
$ cavctl pipeline --key mypipeline --schema site --dryrun
$ cavctl pipeline --key mypipeline --schema site --no-wait
$ cavctl pipeline --key mypipeline --schema site --interval 5

Example:

$ cavctl pipeline --key cleanup --schema server
{
  "pipeline": "cleanup",
  "dryrun": false,
  "handle": "550e8400-e29b-41d4-a716-446655440000",
  "task_url": "http://localhost:8000/api/tasks/550e8400-e29b-41d4-a716-446655440000/"
}
polling task 550e8400-e29b-41d4-a716-446655440000 every 2s ...
  [RUNNING]   0%  starting
  [RUNNING]  50%  25/50
  [DONE]    100%  50/50
  output: {
    "count_ok": 48,
    "count_ko": 2
  }

info

This command calls the configured cavaliba instance and retrive key system informations.

permission required: p_info

$ cavctl info
{
  "schema_count": 20,
  "field_count": 168,
  "instance_count": 956,
  "instance_eav": 9679,
  "instance_file": 0,
  "user_count": 504,
  "group_count": 61,
  "role_count": 14,
  "permission_count": 113,
  "visitor_count": 0,
  "configuration_count": 60,
  "log_count": 46606,
  "apistat_count": 1,
  "dashboard_count": 24,
  "smsjournal_count": 0,
  "status_raw_count": 24186,
  "status_sample_hour_count": 137,
  "status_sample_day_count": 12
}

Reference


    cavctl ping
    cavctl version
    cavctl info

    cavctl user
    cavctl user --page 3 --size 5 --format json
    cavctl user --search admi
    cavctl user --id 1
    cavctl user --key patricia

    cavctl group
    cavctl group --page 1 --size 10 --format yaml
    cavctl group --search cloud
    cavctl group --id 42
    cavctl group --key g_cloud_engineer

    cavctl role
    cavctl role --page 1 --size 10 --format yaml
    cavctl role --search api
    cavctl role --id 42
    cavctl role --key role_admin

    cavctl permission
    cavctl permission --page 1 --size 10 --format yaml
    cavctl permission --search data
    cavctl permission --id 42
    cavctl permission --key p_data_admin

    cavctl schema
    cavctl schema --schema site
    cavctl schema --schema site --format yaml


    cavctl asset --search anco
    cavctl asset --id 35
    cavctl asset --schema site
    cavctl asset --schema site --search anc
    cavctl asset --schema site --key ancon
    cavctl asset --schema site --search anc --format json --page 2 --size 1 --expand
    cavctl asset --schema test --id 968 --refs '_user,*'
    cavctl asset --schema site --key GAVLE --rev 5
    cavctl asset --schema site --key GAVLE --rev 10 --refs '*'

    cavctl task
    cavctl task --state RUNNING
    cavctl task --key <uuid>
    cavctl task --key <uuid> --stop

    cavctl pipeline
    cavctl pipeline --key mypipeline --schema site
    cavctl pipeline --key mypipeline --schema site,server
    cavctl pipeline --key mypipeline --schema site --dryrun
    cavctl pipeline --key mypipeline --schema site --no-wait
    cavctl pipeline --key mypipeline --schema site --interval 5

    # --outfile: append output to a file instead of stdout
    cavctl asset --schema site --outfile /tmp/sites.json

CLI (local)