CLI Commands#

Click command-line interface for jamb.

jamb.cli.commands.cli(*args, **kwargs)#

jamb - IEC 62304 requirements traceability for pytest.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.init(*args, **kwargs)#

Initialize a new jamb project with default IEC 62304 documents.

Creates a ‘reqs’ folder with PRJ, UN, SYS, SRS, HAZ, and RC documents in the standard medical device traceability hierarchy:

PRJ (Project Requirements) - root
+-- UN (User Needs)
|   +-- SYS (System Requirements)
|       +-- SRS (Software Requirements Specification)
+-- HAZ (Hazards)
    +-- RC (Risk Controls)

Also creates an initial PRJ001 heading item using the project name from pyproject.toml (falls back to the current directory name).

b If pyproject.toml exists, adds [tool.jamb] configuration.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.info(*args, **kwargs)#

Display document information.

Shows document structure, hierarchy, and item counts. Lists each discovered document with its active item count and parent relationships, then prints a tree view of the full document hierarchy.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.validate(*args, **kwargs)#

Validate the requirements tree.

Checks for issues like:

  • Cycles in document hierarchy

  • Invalid or missing links

  • Suspect links (items needing re-review)

  • Items without required links

b Examples:

jamb validate              # Run validation
jamb validate -v           # Verbose output
jamb validate --skip UT    # Skip unit test document
jamb validate -S           # Skip suspect checks
Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.check(*args, **kwargs)#

Check test coverage without running tests.

Scans test files for @pytest.mark.requirement markers and reports which items have linked tests.

Note: This is a static scan of test source files and does not execute any tests. Only the @pytest.mark.requirement(...) decorator form is detected; other import styles or aliases are not recognized. For full coverage including test outcomes, use pytest --jamb.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.publish(*args, **kwargs)#

Publish a document.

PREFIX is the document prefix (e.g., SRS) or ‘all’ for all documents. PATH is the output file or directory (optional).

Use –template with a .docx file to apply custom styles. Generate a starter template with: jamb template

For a traceability matrix with test coverage, use: pytest –jamb –jamb-trace-matrix PATH

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.reorder(*args, **kwargs)#

Renumber item UIDs sequentially to fill gaps.

PREFIX is the document identifier (e.g., SRS, UT).

Items are sorted by current UID and renumbered to form a contiguous sequence (e.g., SRS001, SRS002, …). All cross-document links that reference renamed UIDs are updated automatically.

By default, test files with @pytest.mark.requirement() decorators are also updated. Use –no-update-tests to skip this.

If orphaned test references (references to deleted items) would collide with renamed UIDs, the reorder is aborted. Use –clean-orphans to automatically remove such orphaned references before reordering.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

Document Commands#

jamb.cli.commands.doc_create(*args, **kwargs)#

Create a new document.

PREFIX is the document identifier (e.g., SRS, UT). PATH is the directory where the document will be created.

Supports multiple parents for DAG hierarchy:

jamb doc create SRS reqs/srs –parent SYS –parent RC

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.doc_delete(*args, **kwargs)#

Delete a document.

PREFIX is the document identifier to delete (e.g., SRS, UT).

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.doc_list(*args, **kwargs)#

List all documents in the tree.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

Item Commands#

jamb.cli.commands.item_add(*args, **kwargs)#

Add a new item to a document.

PREFIX is the document to add the item to (e.g., SRS, UT).

When using –before or –after, existing items are shifted and test files with @pytest.mark.requirement() decorators are updated automatically. Use –no-update-tests to skip test file updates.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.item_list(*args, **kwargs)#

List items in a document or all documents.

PREFIX is optional - if provided, only list items in that document.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.item_remove(*args, **kwargs)#

Remove an item by UID.

UID is the item identifier (e.g., SRS001, UT002).

If the item is referenced by tests, displays a warning and prompts for confirmation. Use –force to skip the confirmation prompt.

By default, jamb removes @pytest.mark.requirement() decorators referencing the deleted UID. Use –no-update-tests to skip this.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.item_edit(*args, **kwargs)#

Edit an item in the default editor.

UID is the item identifier (e.g., SRS001, UT002).

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.item_show(*args, **kwargs)#

Display item details.

UID is the item identifier (e.g., SRS001, UT002).

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

Review Commands#

jamb.cli.commands.review_mark(*args, **kwargs)#

Mark an item as reviewed.

LABEL is an item UID, document prefix, or ‘all’.

jamb review mark SRS001   # Mark single item
jamb review mark SRS      # Mark all items in SRS document
jamb review mark all      # Mark all items in all documents
Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.review_clear(*args, **kwargs)#

Absolve items of their suspect link status.

LABEL is an item UID, document prefix, or ‘all’. PARENTS optionally limits clearing to links with specific parent UIDs.

jamb review clear SRS001        # Clear suspect links on single item
jamb review clear SRS           # Clear suspect links in SRS document
jamb review clear all           # Clear all suspect links
jamb review clear SRS001 CUS001 # Clear only link to CUS001
Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.review_reset(*args, **kwargs)#

Reset items to unreviewed status.

LABEL is an item UID, document prefix, or ‘all’.

jamb review reset SRS001   # Reset single item
jamb review reset SRS      # Reset all items in SRS document
jamb review reset all      # Reset all items in all documents
Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

Import/Export Commands#

jamb.cli.commands.export_yaml(*args, **kwargs)#

Export documents and items to a YAML file.

OUTPUT is the path to write the YAML file.

jamb export requirements.yml
jamb export reqs.yml --documents SRS,SYS
jamb export output.yml --items SRS001,SRS002
jamb export output.yml --items SRS001 --neighbors
jamb export output.yml --items SRS001 --neighbors --documents SRS,SYS
Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

jamb.cli.commands.import_yaml_cmd(*args, **kwargs)#

Import documents and items from a YAML file.

FILE is the path to a YAML file containing documents and items to create.

Expected YAML schema:

documents:                # optional
  - prefix: SRS           # required - document prefix
    path: reqs/srs        # required - directory path
    parents: [SYS]        # optional - parent document prefixes
    digits: 3             # optional - UID digit count (default: 3)
items:                    # optional
  - uid: SRS001           # required - unique item identifier
    text: "requirement"   # required - item text
    header: "Title"       # optional - section header
    links: [SYS001]       # optional - linked parent item UIDs

Examples:

jamb import requirements.yml
jamb import requirements.yml --dry-run
jamb import requirements.yml --update
jamb import --template > requirements.yml
Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any

Test Case Commands#

jamb.cli.commands.lock_tc(*args, **kwargs)#

Lock TC IDs by inserting @pytest.mark.tc_id decorators into test files.

This command reads the current TC ID assignments from a .jamb file and inserts @pytest.mark.tc_id() decorators into test functions, making the auto-generated IDs permanent.

jamb lock-tc
jamb lock-tc --dry-run
jamb lock-tc --test-dir tests/unit/
Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

t.Any