--- 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//` — 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__read`) The endpoint is selected based on the flags provided: | Flags | Endpoint | |-------|----------| | *(none)* | `assets/` — all assets | | `--id` | `assets//` | | `--schema` | `assets//` — all instances of a schema | | `--schema` + `--key` | `assets///` — 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 `, returns the detail of a single task. Use `--stop` to abort a running task. | Flags | Description | |-------|-------------| | *(none)* | List all tasks | | `--key ` | Task detail | | `--key --stop` | Stop (abort) a running task | | `--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 ` and `--schema `, submits a pipeline run as an async task and polls for completion. | Flags | Description | |-------|-------------| | *(none)* | List all pipelines | | `--key ` + `--schema ` | Run pipeline on the given schemas | | `--dryrun` | Run in dry-run mode (no changes applied) | | `--no-wait` | Submit and return immediately (no polling) | | `--interval ` | 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 cavctl task --key --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 ```