/doca-argp

license: Apache-2.0
name: doca-argp
description: >
  Use this skill for hands-on DOCA Arg Parser CLI work on a shipped
  sample or new DOCA-using app — adding / removing / renaming flags;
  wiring `doca_argp_init` → register params → `doca_argp_start` →
  `doca_argp_destroy` in order; picking a parameter type from the full
  public enum (`DOCA_ARGP_TYPE_STRING`, `_INT`, `_BOOLEAN`, `_DEVICE`,
  `_DEVICE_REP`, `_DOUBLE` — six values, not three); preserving the
  built-in DOCA flags (`-h` `-v` `-l` `--sdk-log-level` `--log-filter`
  `-j`/`--json`, NOT `--json-config`); `--device` is per-program; or
  debugging `DOCA_ERROR_BAD_STATE` / `INVALID_VALUE` / `NOT_SUPPORTED` /
  `IO_FAILED` from `doca_argp_*`. Trigger on implicit phrasings: "add a
  custom flag to a DOCA sample", "should I use getopt here", "BAD_STATE
  registering a new param", "my JSON config key is rejected", or "my
  sample's --json is ignored". Refuse and route elsewhere for
  variadic-flag / subcommand / shell-completion features, DOCA Core
  context, or DOCA Log internals.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - argp
    - cli
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC
  attached. Reads the user's local install via `pkg-config doca-argp`
  and inspects /opt/mellanox/doca/{lib,include,samples,applications}.
  The validation steps require a live DOCA install.

DOCA Arg Parser

Examples

• **"Add a custom flag to a DOCA sample."** — this is in

scope. Register a typed `doca_argp` param; do not drop to getopt.

• **"BAD_STATE registering a new param."** — check init →

register → start order before changing the flag type.

Instructions

Follow Loading order below. Open the tasks companion for configure / register / debug. Open the capabilities companion for the public param types. Do not open every companion file.

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on CLI work** on a DOCA sample or new DOCA-using app. Open the tasks companion if the user wants to *do* something (configure / build / modify / run / test / debug); open the capabilities companion when the question is *what can the Arg Parser express* on this version. If the user has not installed DOCA yet, route to `doca-setup/SKILL.md` first. If the user is about to rewrite a sample's CLI with `getopt` / `argparse` / custom parsing instead of reusing the Arg Parser, read the load-bearing rule in the capabilities companion before any code change.

Example questions this skill answers well

The CLASSES of Arg Parser questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

• **"How do I add a new flag to a DOCA sample without breaking

the standard CLI?"** — worked example: *"add `--my-flag` to `/opt/mellanox/doca/samples/doca_dma/dma_local_copy/` so the sample still accepts `--device <PCI>` and `--sdk-log-level <level>` the same way it did before"*. Answered by the reuse-the-Arg-Parser rule in the capabilities companion

• the register-before-start workflow in

the tasks companion.

• **"Why does `doca_argp_param_set_*` return `BAD_STATE` on my

second call?"** — worked example: *"registering a new param after `doca_argp_start` has already parsed argv"*. Answered by the lifecycle order in the capabilities companion

• the error-taxonomy row in

the capabilities companion for `DOCA_ERROR_BAD_STATE`.

• **"Can I drive a sample from a JSON file instead of a long

command line?"** — worked example: *"point a sample at `./my-config.json` so the operator does not have to type out ten flags every time"*. Answered by the `--json <path>` integration in the capabilities companion

• the JSON-config-file workflow in

the tasks companion and the tasks companion.

• **"My `--my-flag X` value is rejected as `INVALID_VALUE` — why?"** —

worked example: *"declared the param as `int` but passed `--my-flag 0x40`"*. Answered by the parameter-type table in the capabilities companion

• the type-mismatch row in

the capabilities companion.

• **"Is `doca-argp` even on my installed DOCA?"** — worked

example: *"a colleague's sample mentions doca-argp but I want to confirm before I depend on it"*. Answered by the presence

• version-detection rule in

the capabilities companion, which cross-links the canonical detection chain in `doca-version/SKILL.md`.

• **"Should I use doca-argp here, or is this case actually

outside its scope?"** — worked example: *"writing a host-side CLI tool that never calls a `doca_*` symbol"*. Answered by the path-selection rule in the capabilities companion *Use doca-argp when … / Do not use doca-argp when …* bullets.

Audience

This skill serves **external developers building or modifying DOCA-using applications** — i.e., users whose code already calls `doca_*` (directly in C/C++, or through FFI/bindings from another language) and who need the standard DOCA CLI surface so operators of the resulting binary do not have to relearn how to invoke each sample. It is *not* for NVIDIA developers contributing to the Arg Parser library itself.

**Language scope.** DOCA Arg Parser ships as a C library with `pkg-config` module name `doca-argp`. The shipped samples are written in C. C and C++ consumers are the canonical case; the worked examples in the tasks companion assume that path. Other-language consumers (Rust, Go, Python, …) consume the same `*.so` through FFI or language-specific bindings; the skill's contribution in that case is to keep the lifecycle, parameter-type, JSON-config, standard-flag-surface, and error-taxonomy guidance language-neutral, and to route the agent to the public C ABI as the authoritative surface that any wrapper will e