---
title: cavctl
description: cavctl standalone and remote CLI command
weight: 92
---

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

1. Select the appropriate binary from the cavaliba download page
2. Create an API Key in your Cavaliba instance with appropriate permissions (eg. p_info)
3. Optionnaly, create a ~/cavaliba/cavctl.yaml configuration file
4. 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.

```bash
$ 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:

```yaml cavaliba.yaml
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.

```bash
$ 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.

```bash
# 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

```bash
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


```bash
$ 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`

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

Example:
```bash
$ 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`

```bash
$ 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:
```bash
$ 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`.

```bash
$ cavctl schema
$ cavctl schema --schema site
$ cavctl schema --schema site --format yaml
```

Example:
```bash
$ 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`.

```bash
$ 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:
```bash
$ 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`

```bash
$ 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:
```bash
$ 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`

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

Example:
```bash
$ 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` |

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

Example:
```bash
$ 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) |

```bash
$ 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:
```bash
$ 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

```bash
$ 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

```bash

    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

```


