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/default.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:
  get         displays asset 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
  remote      displays remote cavaliba version
  schema      display schema information from Cavaliba instance
  task        displays task information
  version     displays cavctl local 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
  -f, --field string           Field filter
      --file string            File path for import/export operations
  -h, --help                   help for cavctl
  -i, --id int                 ID filter
  -k, --key string             Key filter
      --outfile string         Append results to file instead of stdout
  -o, --output string          Output format : json, yaml, txt, csv (case-insensitive) (default "json")
      --page int               Page number
  -p, --pipeline string        Pipeline name for data transformation
  -q, --query string           Search query filter
      --refs string            Refs filter
      --rev int                Number of revisions to include
  -s, --schema string          Schema filter
      --size int               Page size
      --ssl_skipverify         skip TLS/SSL cert verification
      --sync                   Import: enable sync mode (touch last_sync on imported instances)
      --timeout int            API timeout (msec) (default 7000)
      --url string             Cavaliba Root URL (default "http://localhost:8000/api/")
  -v, --verbose                verbose output
      --version                version for cavctl

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

Note: -f was reassigned from the old --format flag to --field when --field was added. --format was later renamed to --output/-o, and now accepts json/yaml/txt (or text) case-insensitively (e.g. JSON, YAML, TXT, TEXT all work), plus csv.

Empty command

Running cavctl with no arguments or flags displays help (same as cavctl --help).

To print the local cavctl version, use --version or the version subcommand — they are equivalent, and neither calls the remote API (use cavctl remote for that).

$ cavctl
cavctl is a CLI standalone command to manage remote Cavaliba systems
...
Use "cavctl [command] --help" for more information about a command.

$ cavctl --version
cavctl version: 2.1.0

$ cavctl version
cavctl version: 2.1.0

Explicit command-line parameters

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

$ cavctl remote --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 remote --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 --conf myconfig.yaml

By default, cavctl will try $HOME/.cavaliba/default.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 remote -v
----- Configuration -----
Configuration:   /home/cavaliba/.cavaliba/default.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 get --schema site --outfile /tmp/sites.json

# Collect multiple commands into the same file
cavctl get --schema user --outfile results.json
cavctl get --schema 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"
}

remote

New name: v2.0.0 (was 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 remote
{
    "version": "3.21.0"
    "cavctl_supported_version": "1.7.0"
}

version

New: v2.0.0

Displays the local cavctl binary version. Equivalent to the --version flag. Does not call the remote instance — no permission required, no config/credentials needed.

Permission required: None

$ cavctl version
cavctl version: 2.1.0

$ cavctl --version
cavctl version: 2.1.0

permission

New: v3.32.0

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

Permission required: p_permission_read

$ cavctl permission
$ cavctl permission -i 42
$ cavctl permission -k p_data_admin
$ cavctl permission -q data
$ cavctl permission --page 1 --size 10 --output yaml

Example:

$ cavctl permission -k 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/-s, returns the list of all schemas. With --schema/-s, returns the full field definition of a single schema.

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

Additional options: --output.

$ cavctl schema
$ cavctl schema --schema site
$ cavctl schema -s site --output 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
  }
}

get

New name: v2.0.0 (was asset). Aliases asset/assets/instance/instances were removed — get is the only name now.

Retrieves asset (instance) information from the remote Cavaliba instance.

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`, `-i`	`assets/<id>/`
`--schema`, `-s`	`assets/<schema>/` — all instances of a schema
`--schema`/`-s` + `--key`/`-k`	`assets/<schema>/<key>/` — single instance

--key/-k without --schema/-s (and without --id/-i) is rejected with an error rather than silently listing all assets, since a key alone can’t be resolved without knowing its schema.

Additional options: --query/-q, --page, --size, --output, --expand, --refs, --rev, --field/-f.

$ cavctl get
$ cavctl get -i 35
$ cavctl get -s site
$ cavctl get --schema site -q anc
$ cavctl get -s site -k GAVLE
$ cavctl get --schema site --query anc --output yaml --page 2 --size 5
$ cavctl get --schema site --key GAVLE --expand
$ cavctl get --schema test --id 968 --refs 'user,*'
$ cavctl get --schema site --key GAVLE --rev 5
$ cavctl get --schema site --key GAVLE --rev 10 --refs '*'

Example:

$ cavctl get -s site -k GAVLE
{
  "id": 42,
  "classname": "site",
  "keyname": "GAVLE",
  "displayname": "Gavle Rehabilitation Center",
  "country": "SE",
  "zip": "80256"
}

csv output

New: v2.0.0

-o csv/--output csv converts the API response into CSV, client-side, in cavctl — the server always returns JSON under the hood for this mode; csv is not a wire format. Output is always a horizontal table: the first line is a header row (alphabetically sorted union of keys across all objects, minus the id/classname instance-metadata columns, always dropped), and each subsequent line is one object — including for a single-instance lookup (--id/--key), which still renders as one header row plus its single data row, not a transposed field/value list.

New: v2.1.0 — id/classname are always dropped from CSV output.

Cell values: scalars render directly; an array of up to 20 scalar values is joined into one cell with ^ (e.g. aaa^bbb^ccc); anything that doesn’t fit a flat cell — a longer array, an array containing objects, or a nested object — renders as an empty cell rather than a garbled blob.

The CSV delimiter is shared with CSV import: use --delimiter to change it from the default comma.

$ cavctl get -s site -o csv
$ cavctl get -s site -o csv --delimiter ';'
$ cavctl get -s site -k GAVLE -o csv

Example (list):

$ cavctl get -s group -o csv
keyname,displayname,is_enabled,users
g_cloud_engineer,Cloud Engineers,true,alice^bob
g_admins,Administrators,true,

Example (single object — still header + one row):

$ cavctl get -i 1 -o csv
displayname,firstname,keyname,lastname,want_email
Built-in Global Admin user,,admin,,true

user / group / role

Removed: v2.0.0 — the dedicated cavctl user, cavctl group, cavctl role commands were replaced by get. Since the Cavaliba user-schema upgrade, user, group, and role are plain schema keynames like any other asset schema — nothing special is needed in cavctl for them.

$ cavctl get --schema user
$ cavctl get -s user -k adela81
$ cavctl get -s group -k g_cloud_engineer
$ cavctl get -s role -k role_admin

Example:

$ cavctl get -s user -k 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
}

task

New: v1.8.0

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

Permission required: p_info

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

Flags	Description
(none)	List all tasks
`--key`/`-k <uuid>`	Task detail
`--key`/`-k <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 -k 550e8400-e29b-41d4-a716-446655440000
$ cavctl task -k 550e8400-e29b-41d4-a716-446655440000 --stop

Example:

$ cavctl task -k 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/-k, returns the list of pipelines. With --key/-k <name> and --schema/-s <schemas>, submits a pipeline run as an async task and polls for completion.

Flags	Description
(none)	List all pipelines
`--key`/`-k <name>` + `--schema`/`-s <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 -k mypipeline -s 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 -k cleanup -s 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
  }

import

Import schemas or instances from a YAML, JSON, or CSV file into the remote Cavaliba instance. Content-Type is auto-detected from the file extension: .yaml/.yml → application/x-yaml, .json → application/json, .csv → text/csv. Any other extension is rejected.

Permission required: p_data_import

Flags	Description
`--file <path>`	Required. File to import
`--batch <n>`	CSV only: split the file into chunks of `n` rows and POST them one at a time instead of the whole file in one request (default: 0 = disabled, single request). Ignored for `.yaml`/`.yml`/`.json`
`--delimiter`	CSV field delimiter, used both to read the input file and to re-serialize each batch (default: `,`)
`--sync`	Sends `sync=true` to the API, enabling sync mode: `last_sync` is touched on every imported instance, even when the rest of the data is unchanged. With `--batch`, applied to every chunk request

Without --batch (or with YAML/JSON), the whole file is POSTed in a single request and the raw API response is printed via the usual --output/--outfile handling.

$ cavctl import --file data.yaml
$ cavctl import --file data.json
$ cavctl import --file data.csv
$ cavctl import --file data.csv --sync

With --batch on a CSV file, cavctl chunks the file client-side (re-adding the header to each chunk) and POSTs each batch separately, printing per-chunk progress to stderr as it goes, then a final {count, count_ok, count_ko} summary to stdout (subject to --output/--outfile like any other command). Exits non-zero if no chunk could be read, or if every chunk failed.

$ cavctl import --file data.csv --batch 500
$ cavctl import --file data.csv --batch 500 --delimiter ';'

Example:

$ cavctl import --file data.csv --batch 2
Processing
----------
Importing data.csv in batches of 2 rows...

Chunk 1   - 2 rows - DONE - success: 2    - errors: 0
Chunk 2   - 2 rows - DONE - success: 1    - errors: 1

Import Summary:
--------------
Total chunks:      2
Successful chunks: 2
Failed chunks:     0
Total rows:        4
Success rows:      3
Error rows:        1
Duration:          0.4s
{
  "count": 4,
  "count_ok": 3,
  "count_ko": 1
}

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 remote
    cavctl version
    cavctl --version
    cavctl info

    # user, group, role are plain schema keynames (no dedicated commands) — use get
    cavctl get --schema user
    cavctl get --schema user --page 3 --size 5 --output json
    cavctl get --schema user --query admi
    cavctl get --schema user --key patricia

    cavctl get --schema group
    cavctl get --schema group --page 1 --size 10 --output yaml
    cavctl get --schema group --query cloud
    cavctl get --schema group --key g_cloud_engineer

    cavctl get --schema role
    cavctl get --schema role --page 1 --size 10 --output yaml
    cavctl get --schema role --query api
    cavctl get --schema role --key role_admin

    cavctl permission
    cavctl permission --page 1 --size 10 --output yaml
    cavctl permission --query data
    cavctl permission --id 42
    cavctl permission --key p_data_admin

    cavctl schema
    cavctl schema --schema site
    cavctl schema --schema site --output yaml


    cavctl get --query anco
    cavctl get --id 35
    cavctl get --schema site
    cavctl get --schema site --query anc
    cavctl get --schema site --key ancon
    cavctl get --schema site --query anc --output json --page 2 --size 1 --expand
    cavctl get --schema test --id 968 --refs 'user,*'
    cavctl get --schema site --key GAVLE --rev 5
    cavctl get --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 get --schema site --outfile /tmp/sites.json

    # -o csv: client-side CSV conversion (server still returns JSON)
    cavctl get --schema site -o csv
    cavctl get --schema site -o csv --delimiter ';'

CLI (local)