cavctl – cavaliba.com
Description: cavctl standalone and remote CLI command

`CTRL K`

Documentation
cavctl

# 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

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/default.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:
      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)