CLI Command Reference

Complete reference for all ucis sub-commands and options.

Manipulate UCIS coverage data

usage: ucis [-h]
            {convert,merge,list-db-formats,list-rpt-formats,report,show,view,history,testplan}
            ...

Sub-commands

convert

Converts coverage data from one format to another

ucis convert [-h] --out OUT [--input-format INPUT_FORMAT]
             [--output-format OUTPUT_FORMAT] [--strict] [--warn-summary]
             input

Positional Arguments

input: Source database to convert

Named Arguments

--out, -o

Specifies the output of the conversion

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’. Valid formats: avl-json, cocotb-xml, cocotb-yaml, libucis, sqlite, vltcov, xml, yaml

--output-format, -of

Specifies the format of the output database. Defaults to ‘xml’. Valid formats: avl-json, cocotb-xml, cocotb-yaml, libucis, sqlite, vltcov, xml, yaml

--strict

Treat any lossy conversion as an error (raises ConversionError)

Default: False

--warn-summary

Print a summary of conversion warnings at the end

Default: False

merge

Merges coverage data from two or more databases into a single merged database

ucis merge [-h] --out OUT [--input-format INPUT_FORMAT]
           [--output-format OUTPUT_FORMAT] [--libucis LIBUCIS]
           [--squash-history] [--fast] [--workers WORKERS]
           db [db ...]

Positional Arguments

db

Named Arguments

--out, -o

Specifies the output of the merge

--input-format, -if

Specifies the format of the input databases. Defaults to ‘xml’

--output-format, -of

Specifies the format of the input databases. Defaults to ‘xml’

--libucis, -l

Specifies the name/path of the UCIS shared library

--squash-history

Collapse per-test history into a single summary node

Default: False

--fast

Use optimised merge path (SQLite-to-SQLite only)

Default: False

--workers, -j

Number of parallel reader threads for merge_fast (default: 4)

Default: 4

list-db-formats

Shows available database formats

ucis list-db-formats [-h]

list-rpt-formats

Shows available report filters

ucis list-rpt-formats [-h]

report

Generate a report (typically textual) from coverage data

ucis report [-h] [--out OUT] [--input-format INPUT_FORMAT]
            [--output-format OUTPUT_FORMAT]
            db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o: Specifies the output location for the report
--input-format, -if: Specifies the format of the input database. Defaults to ‘xml’
--output-format, -of: Specifies the output format of the report. Defaults to ‘txt’

show

Query and display coverage information from UCIS database

ucis show [-h]
          {summary,gaps,covergroups,bins,tests,hierarchy,metrics,compare,hotspots,code-coverage,assertions,toggle}
          ...

Positional Arguments

show_cmd: Possible choices: summary, gaps, covergroups, bins, tests, hierarchy, metrics, compare, hotspots, code-coverage, assertions, toggle

Sub-commands

summary

Display overall coverage summary

ucis show summary [-h] [--out OUT] [--input-format INPUT_FORMAT]
                  [--output-format {json,text,txt}]
                  db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

gaps

Display coverage gaps (uncovered bins and coverpoints)

ucis show gaps [-h] [--out OUT] [--input-format INPUT_FORMAT]
               [--output-format {json,text,txt}] [--threshold THRESHOLD]
               db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

--threshold, -t

Only show coverpoints with coverage below this threshold (0-100)

covergroups

Display detailed covergroup information

ucis show covergroups [-h] [--out OUT] [--input-format INPUT_FORMAT]
                      [--output-format {json,text,txt}] [--include-bins]
                      db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

--include-bins, -b

Include detailed bin information

Default: False

bins

Display bin-level coverage details

ucis show bins [-h] [--out OUT] [--input-format INPUT_FORMAT]
               [--output-format {json,text,txt}] [--covergroup COVERGROUP]
               [--coverpoint COVERPOINT] [--min-hits MIN_HITS]
               [--max-hits MAX_HITS] [--sort {count,name}]
               db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

--covergroup, -cg

Filter by covergroup name

--coverpoint, -cp

Filter by coverpoint name

--min-hits

Show only bins with at least this many hits

--max-hits

Show only bins with at most this many hits

--sort, -s

Possible choices: count, name

Sort bins by ‘count’ or ‘name’

tests

Display test execution information

ucis show tests [-h] [--out OUT] [--input-format INPUT_FORMAT]
                [--output-format {json,text,txt}]
                db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

hierarchy

Display design hierarchy structure

ucis show hierarchy [-h] [--out OUT] [--input-format INPUT_FORMAT]
                    [--output-format {json,text,txt}] [--max-depth MAX_DEPTH]
                    db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

--max-depth, -d

Maximum depth to traverse

metrics

Display coverage metrics and statistics

ucis show metrics [-h] [--out OUT] [--input-format INPUT_FORMAT]
                  [--output-format {json,text,txt}]
                  db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

compare

Compare coverage between two databases

ucis show compare [-h] [--out OUT] [--input-format INPUT_FORMAT]
                  [--output-format {json,text,txt}]
                  db compare_db

Positional Arguments

db: Path to the baseline coverage database
compare_db: Path to the comparison database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

hotspots

Identify coverage hotspots and high-value targets

ucis show hotspots [-h] [--out OUT] [--input-format INPUT_FORMAT]
                   [--output-format {json,text,txt}] [--threshold THRESHOLD]
                   [--limit LIMIT]
                   db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format. Defaults to ‘json’

Default: 'json'

--threshold, -t

Coverage threshold for low-coverage groups (default: 80)

Default: 80.0

--limit, -l

Maximum number of items to show per category (default: 10)

Default: 10

code-coverage

Display code coverage with support for LCOV/Cobertura formats

ucis show code-coverage [-h] [--out OUT] [--input-format INPUT_FORMAT]
                        [--output-format {json,text,txt,lcov,cobertura,jacoco,clover}]
                        db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt, lcov, cobertura, jacoco, clover

Specifies the output format

Default: 'json'

assertions

Display assertion coverage information

ucis show assertions [-h] [--out OUT] [--input-format INPUT_FORMAT]
                     [--output-format {json,text,txt}]
                     db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format

Default: 'json'

toggle

Display toggle coverage information

ucis show toggle [-h] [--out OUT] [--input-format INPUT_FORMAT]
                 [--output-format {json,text,txt}]
                 db

Positional Arguments

db: Path to the coverage database

Named Arguments

--out, -o

Specifies the output location for the report

--input-format, -if

Specifies the format of the input database. Defaults to ‘xml’

--output-format, -of

Possible choices: json, text, txt

Specifies the output format

Default: 'json'

view

Launch interactive Terminal UI for exploring coverage data

ucis view [-h] [--input-format INPUT_FORMAT] db

Positional Arguments

db: Path to the coverage database

Named Arguments

--input-format, -if: Specifies the format of the input database. Defaults to ‘xml’

history

Query and display test history from an NCDB .cdb file

ucis history [-h] {query,stats} ...

Positional Arguments

history_cmd: Possible choices: query, stats

Sub-commands

query

Display history records for a specific test

ucis history query [-h] [--from DATE] [--to DATE] [--out OUT]
                   [--output-format {text,json}]
                   db test_name

Positional Arguments

db: Path to the NCDB .cdb file
test_name: Test name to query

Named Arguments

--from

Start date (ISO 8601 or Unix timestamp)

--to

End date (ISO 8601 or Unix timestamp)

--out, -o

Output file (default: stdout)

--output-format, -of

Possible choices: text, json

Output format (default: text)

Default: 'text'

stats

Show test statistics (flaky, failing, or named test)

ucis history stats [-h] [--top-flaky N] [--top-failing N] [--out OUT]
                   [--output-format {text,json}]
                   db [test_name]

Positional Arguments

db: Path to the NCDB .cdb file
test_name: Show stats for a specific test name

Named Arguments

--top-flaky

Show top N flaky tests

--top-failing

Show top N failing tests

--out, -o

Output file (default: stdout)

--output-format, -of

Possible choices: text, json

Output format (default: text)

Default: 'text'

testplan

Manage and evaluate testplans embedded in NCDB .cdb files

ucis testplan [-h] {import,closure,export-junit} ...

Positional Arguments

testplan_cmd: Possible choices: import, closure, export-junit

Sub-commands

import

Import an Hjson/JSON testplan and embed it in a .cdb file

ucis testplan import [-h] [--subs KEY=VAL] db hjson_path

Positional Arguments

db: Path to the NCDB .cdb file
hjson_path: Path to the .hjson or .json testplan file

Named Arguments

--subs

Template substitution (repeatable): e.g. –subs uart=uart0

Default: []

closure

Compute and display testpoint closure

ucis testplan closure [-h] [--testplan PATH] [--waivers PATH] [--stage STAGE]
                      [--out OUT] [--output-format {text,json}]
                      db

Positional Arguments

db: Path to the NCDB .cdb file

Named Arguments

--testplan

External testplan JSON file (overrides embedded)

--waivers

External waivers JSON file (overrides embedded)

--stage

Evaluate a stage gate (e.g. V2)

--out, -o

Output file (default: stdout)

--output-format, -of

Possible choices: text, json

Output format (default: text)

Default: 'text'

export-junit

Export testpoint closure results as JUnit XML

ucis testplan export-junit [-h] [--testplan PATH] [--out OUT]
                           [--suite-name NAME]
                           db

Positional Arguments

db: Path to the NCDB .cdb file

Named Arguments

--testplan: External testplan JSON file (overrides embedded)
--out, -o: Output XML file (default: closure_results.xml)
--suite-name: JUnit testsuite name attribute

For workflow-oriented usage see the user guides:

Analyzing Coverage — show commands workflow
Merging Coverage — merge options
Exporting to CI/CD Formats — show code-coverage export formats
Test History — history query / history stats
Testplan Integration — testplan import / testplan closure / testplan export-junit