Using ubc in CI/CD

ubc is a standalone binary that exposes the full ubCode engine on the command line. Use it locally as part of a pre-commit hook, in CI/CD pipelines to gate pull requests, or on the console to explore project insights.

ubc features explorative help pages. Add -h/--help to any command to see the available options. Many commands directly show the help page when executed without any options and arguments.

Some notes:

  • ubc check shows warnings for individual files while ubc build index reports warnings for the whole project, so it can also consider needs graph problems such as duplicate IDs across multiple files.

  • ubc build index builds a project index including caches just like ubCode. Therefore it makes sense to keep ubCode and ubc versions in sync.

When to Use

  • Running linting or formatting on files with ubc check or ubc format

  • Building project indexes, needs, or reference targets

  • Managing ubcode project configuration, licenses, or schemas

  • Diffing needs between project versions or git refs

  • Scaffolding new ubcode projects with ubc quickstart

Examples

# Lint all files in the current directory
ubc check .

# Format files, failing if any would change (CI mode)
ubc format --check .

# Build the needs index as JSON
ubc build needs . -f json -o needs.json

# Show resolved configuration
ubc config . --indent 2

# Diff needs between two git refs
ubc diff git main feature-branch

Global Options

Options:

  • --version (BOOL) — Show the version and exit

Commands

ubc completions

Generate shell completions

Arguments:

  • shell (CHOICE(bash, elvish, fish, powershell, zsh)) — The shell to generate completions for. If not provided, the shell will be guessed from the environment

ubc check

Run linting checks on individual files or directories.

Each file will be processed against its nearest configuration file, or the default configuration if no configuration file is found

Arguments:

  • files (PATH) (required) — Files or directories to run checks on

Options:

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --extend-ignore (TEXT) — Comma-separated list of additional diagnostic codes to ignore

  • --isolated (BOOL) — Do not read any configuration files, use only the default configuration

  • --config-file (PATH) — The path to a specific configuration file to use for all files

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

ubc format

Run formatting on individual files or directories.

Each file will be processed against its nearest configuration file, or the default configuration if no configuration file is found

Arguments:

  • files (PATH) (required) — Files or directories to run formatting on

Options:

  • --check, --no-check (BOOL) — Avoid writing any formatted files back; instead, exit with a non-zero status code if any files would have been modified, and zero otherwise

  • --isolated, --no-isolated (BOOL) — Do not read any configuration files, use only the default configuration

  • --config-file (PATH) — The path to a specific configuration file to use for all files

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --preview, --no-preview (BOOL) — Activate this command in preview mode

ubc clean

Clear any caches in the directory and any subdirectories

Arguments:

  • path (PATH) — The path to the directory to clean (defaults to the current directory)

ubc config

Show the nearest configuration in JSON format, resolving any extends and defaults

Arguments:

  • path (PATH) — The path to start the config search from (defaults to the current directory)

Options:

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • -i, --indent (INT) — Number of spaces to indent JSON Default: 0.

  • --default, --no-default (BOOL) — Show the default configuration instead

  • --schema, --no-schema (BOOL) — Show the configuration schema instead

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

ubc script

Run a script defined in ubproject.toml

Arguments:

  • key (TEXT) (required) — The script key to execute

Options:

  • --path (PATH) — The path to the project root (defaults to the current directory)

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

ubc quickstart

Create an example ubcode project

Arguments:

  • path (PATH) — The path to write to (defaults to the current directory)

Options:

  • -o, --overwrite (BOOL) — Overwrite existing files

  • -f, --flavor (CHOICE(minimal, full, markdown, variants)) — The project flavor to scaffold Default: minimal.

ubc agent-skill

Generate a SKILLS.md describing all CLI commands for AI agents.

Introspects the full CLI tree and produces a Markdown reference listing every command, sub-command, argument, and option together with the ubc version that generated the document

Options:

  • -o, --output (PATH) — Path to write the SKILLS.md file. If omitted, prints to stdout

  • --sort-commands, --no-sort-commands (BOOL) — Whether to sort commands alphabetically (default to order in help)

ubc build

Commands for building projects

ubc build list-documents

Print out a list of the documents that would be indexed for this project

Arguments:

  • path (PATH) — The path to the project root (defaults to the current directory)

Options:

  • --codelinks, --no-codelinks (BOOL) — Also list files for codelinks projects

  • --codelinks-project (TEXT) — Only list files for a specific codelinks project (implies --codelinks)

  • --source-documents, --no-source-documents (BOOL) — List the source documents (RST/MD files)

  • --parser (BOOL) — Print the parser name alongside each source document

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

ubc build index

Index the project and report warnings.

Returns a non-zero exit code if warnings are found

Arguments:

  • path (PATH) — The path to the project root (defaults to the current directory)

Options:

  • -w, --show-warnings (BOOL) — Show all warnings found during indexing

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --lint-extend-ignore (TEXT) — Comma-separated list of additional diagnostic codes to ignore

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

ubc build needs

Build the needs index and output to a file

Arguments:

  • path (PATH) — The path to the project root (defaults to the current directory)

Options:

  • -f, --format (CHOICE(json, parquet)) — The output format Default: json.

  • -o, --outpath (PATH) — The path to the output file

  • --source-maps, --no-source-maps (BOOL) — Include source map information for each need

  • --content, --no-content (BOOL) — Include the content field for each need

  • --pretty, --no-pretty (BOOL) — Pretty print the JSON output

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

ubc build validate-json

Validate a needs.json file

Arguments:

  • path (PATH) (required) — The path to the needs.json file

  • ids (TEXT) — Only validate certain need IDs

Options:

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

ubc build targets

Build the reference targets index and output to a file (experimental)

Arguments:

  • path (PATH) — The path to the project root (defaults to the current directory)

Options:

  • -f, --format (CHOICE(inv)) — The output format Default: inv.

  • -o, --outpath (PATH) — The path to the output file

  • --compress, --no-compress (BOOL) — Whether to compress the inv file with zlib

  • --srcdir (PATH) — The source directory to relativize paths to (defaults to project.srcdir)

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

ubc license

Commands for managing licenses

ubc license show

Show information for the current license

Options:

  • -k, --key (TEXT) — The license key to show information for, otherwise look in configuration Env: UBCODE_LICENSE_KEY.

  • -u, --user (TEXT) — The user identifier for user-based licenses Env: UBCODE_LICENSE_USER.

  • --dev, --no-dev (BOOL) — Use the development product

  • --json, --no-json (BOOL) — Print output as JSON. Implies –quiet

  • --show-activated, --no-show-activated (BOOL) — Show activated machines

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

ubc license hash

Show hash for a given user e-mail

Options:

  • -u, --user (TEXT) — User e-mail to hash. If not provided, look in configuration Env: UBCODE_LICENSE_USER.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

ubc license activate

Activate the current license

Options:

  • -k, --key (TEXT) — The license key to activate, otherwise look in configuration Env: UBCODE_LICENSE_KEY.

  • -u, --user (TEXT) — The license user to activate, otherwise look in configuration Env: UBCODE_LICENSE_USER.

  • --dev, --no-dev (BOOL) — Use the development product

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

ubc license config-file

Show the path to the license configuration file

ubc license clean

Clear the ublicense cache.

This is useful to refresh the license activation before going offline for a while

ubc schema

Commands for ontology schema validation

ubc schema validate

Validate needs against the ontology schema

Arguments:

  • path (PATH) — The path to the project root (defaults to the current directory)

Options:

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • --show-warnings (BOOL) — Show all build warnings/diagnostics alongside validation results

  • --lint-extend-ignore (TEXT) — Comma-separated list of additional diagnostic codes to ignore

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

ubc query

Query needs in a ubcode project

ubc query filter

Filter and display needs using a Python-like expression

Arguments:

  • filter_expr (TEXT) — Python-like filter expression, e.g. type == "req" and status == "open"

Options:

  • -p, --project (PATH) — Path to the project root or any file within it (defaults to cwd)

  • --field (TEXT) — Field to include in output (repeatable). Defaults to id, type, title

  • -f, --format (CHOICE(table, json)) — Output format Default: table.

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

ubc report

Render a report template against the project’s needs index

Arguments:

  • template_name (TEXT) — Name of the .html.j2 template to render, looked up under the project’s reports directory ([reports].directory in ubproject.toml). Omit if using –list

Options:

  • --list (BOOL) — List the available .html.j2 templates instead of rendering

  • -o, --outpath (PATH) — Path to write the rendered HTML to. Defaults to ‘/_build/.html’

  • -p, --project (PATH) — Path to the project root or any file within it (defaults to cwd)

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --config-name (TEXT) — Configuration file name to search for Default: ubproject.toml.

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

ubc diff

Diff & impact analysis for local projects and needs.json

Options:

  • -n, --needs (PATH) — Needs.json file path (can be used twice for comparison)

  • -p, --project (PATH) — Project path (can be used twice for comparison)

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’ Env: UBCODE_CONFIG_OVERRIDE.

  • --impact (BOOL) — Enable impact analysis

  • --impact-depth (INT) — Set impact analysis link depth Default: 1.

  • --impact-direction (CHOICE(outgoing, incoming, both)) — Set impact analysis direction Default: both.

  • --impact-max-chains (INT) — Maximum number of impact chains per changed need (0 = unlimited) Default: 20.

  • --allow-type (TEXT) — Allow-filter for need types (repeatable)

  • --deny-type (TEXT) — Deny-filter for need types (repeatable)

  • --allow-core (TEXT) — Allow-filter for core fields (repeatable)

  • --deny-core (TEXT) — Deny-filter for core fields (repeatable)

  • --allow-extra (TEXT) — Allow-filter for extra fields (repeatable)

  • --deny-extra (TEXT) — Deny-filter for extra fields (repeatable)

  • --allow-link (TEXT) — Allow-filter for link types (repeatable)

  • --deny-link (TEXT) — Deny-filter for link types (repeatable)

  • --deny-externals (BOOL) — Deny-filter external needs

  • -f, --format (CHOICE(html, console)) — Output format Default: console.

  • -o, --outpath (PATH) — Output file path (for HTML format)

  • --html-theme (CHOICE(dark, light, auto)) — HTML theme for output Default: auto.

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

ubc diff git

Git-based diff and impact analysis

Arguments:

  • ref1 (TEXT) — First git reference (branch/tag/commit)

  • ref2 (TEXT) — Second git reference (branch/tag/commit)

Options:

  • -p, --project (PATH) — Project path. Defaults to the current working directory

  • -n, --needs (PATH) — Needs.json file path in the repository

  • --staged (BOOL) — Compare the staging area with HEAD

  • --impact (BOOL) — Enable impact analysis

  • --impact-depth (INT) — Set impact analysis link depth Default: 1.

  • --impact-direction (CHOICE(outgoing, incoming, both)) — Set impact analysis direction Default: both.

  • --impact-max-chains (INT) — Maximum number of impact chains per changed need (0 = unlimited) Default: 20.

  • --allow-type (TEXT) — Allow-filter for need types (repeatable)

  • --deny-type (TEXT) — Deny-filter for need types (repeatable)

  • --allow-core (TEXT) — Allow-filter for core fields (repeatable)

  • --deny-core (TEXT) — Deny-filter for core fields (repeatable)

  • --allow-extra (TEXT) — Allow-filter for extra fields (repeatable)

  • --deny-extra (TEXT) — Deny-filter for extra fields (repeatable)

  • --allow-link (TEXT) — Allow-filter for link types (repeatable)

  • --deny-link (TEXT) — Deny-filter for link types (repeatable)

  • --deny-externals (BOOL) — Deny-filter external needs

  • -f, --format (CHOICE(html, console)) — Output format Default: console.

  • -o, --outpath (PATH) — Output file path (for HTML format)

  • --html-theme (CHOICE(dark, light, auto)) — HTML theme for output Default: auto.

  • --cache, --no-cache (BOOL) — Use on-disk cache reads

  • -v, --verbose (BOOL) — Show debug information

  • -q, --quiet (BOOL) — Only show errors and warnings

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

ubc serve

Run a ubcode server

ubc serve mcp

Run the Model Context Protocol (MCP) server over stdio

Options:

  • --default-config (PATH) — Path to the default ubproject.toml configuration file

  • -c, --config (TEXT) — Configuration override (repeatable). Example: lint.ignore = ["W001"]

  • --license-key (TEXT) — Use a specific license key Env: UBCODE_LICENSE_KEY.

  • --license-user (TEXT) — Use a specific license user Env: UBCODE_LICENSE_USER.

  • --license-stage (CHOICE(prod, dev)) — Use a specific license stage Env: UBCODE_LICENSE_STAGE.

ubc serve lsp

Run the language server over stdio (or TCP with --port)

Options:

  • -p, --port (INT) — Start a TCP instance of the language server listening on the given port

  • --log-to-output (CHOICE(always, debug, info, warning, error, off)) — When to log to the output channel Default: info.

  • --show-notifications (CHOICE(always, debug, info, warning, error, off)) — When to show notifications Default: error.

  • -c, --config (TEXT) — Configuration override (repeatable). Example: ‘lint.ignore = [“W001”]’