/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 standard `--device` / `--representor` /
  `--json` (`-j`; real flag is `--json`, NOT `--json-config`) /
  `--sdk-log-level` surface; 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:
  kind: library
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}.

DOCA Arg Parser

**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 [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) 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`](../../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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) 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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the register-before-start workflow in

[`TASKS.md ## modify`](TASKS.md#modify).

• **"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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the error-taxonomy row in

[`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) 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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the JSON-config-file workflow in

[`TASKS.md ## modify`](TASKS.md#modify) and [`TASKS.md ## run`](TASKS.md#run).

• **"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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the type-mismatch row in

[`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).

• **"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

[`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which cross-links the canonical detection chain in [`doca-version`](../../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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) *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 `TASKS.md` 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 eventually c