ReqText

ReqText is a CLI & TUI requirements management tool designed to help you easily create, manage and visualize your requirements from the command line. The tool is built on my FlatHier (Short for Flat Hierarchy) library, which creates a manipulates hierarchical data structure in a flat, ordered json. Making it human readable and git ready.

ReqText Installation

Available over npm:

npm install reqtext
npx reqt --help

or for global installation:

npm install -g reqtext
reqt --help

✅ Both reqtext and reqt are valid commands. For convenience, reqt is the preferred shorthand.

ReqText Commands

CLI Reference

General Commands

| Command | Description | |------------------------|--------------------------------------| | version, --version, -v | Show version number | | help, --help, -h | Show help text | | init <project name> | Initialize a new ReqText project | | editor | Launch the interactive terminal editor | | clean, -c | Ensure all items have a valid reqt_id. |

Note: The main purpose of clean is if an AI coding tool adds an item directly in the .reqt.json, or .reqt.md. Use the README_AI.reqt.json as context for the AI tool to learn how to properly use the CLI inputs for it to add or modify items.

Item Management Commands

| Command | Description | Usage Example | |--------------------------------|-------------------------------------------|----------------| | add-item, -a | Add an item to the end of the project | reqt add-item "New Item" | | add-after, -aa | Add an item after a specific outline ID | reqt add-after 1.2 "New Subitem" | | delete, -d | Delete an item by outline number | reqt delete 1.3 | | make-children, -mc | Demote an item (and its children) | reqt make-children 1.2 | | make-sibling, -ms | Promote an item (and its children) | reqt make-sibling 1.2 | | edit-title, -et | Edit the title of an item by outline ID | reqt edit-title 1.2 "Updated Title" | | set-status, -ss | Set the status of an item | reqt set-status 1.2 NEW | | test-exists, -te | Mark test as existing for an item | reqt test-exists 1.2 true | | test-passed, -tp | Mark test as passed for an item | reqt test-passed 1.2 true |

Markdown Editing Workflow

ReqText supports a markdown-based editing workflow that lets you "check out" requirements from .reqt.json for easy editing of long-form fields (requirement, acceptance, details) in markdown. This user-friendly format allows you to preview the future README, including rendering mermaid diagrams stored in .reqt.json.

You can export requirements to a markdown file, edit them in your preferred editor, and then import changes back into the .reqt.json source of truth. This workflow streamlines bulk editing and review of requirement text.

| Command | Description | |------------------------|------------------------------------------------------------------| | out-md, -omd | Export requirements to markdown for editing. | | in-md, -imd | Import changes from markdown back into .reqt.json. Use --keep or -k to retain the markdown file. | | diff | Show differences between .reqt.json and the markdown file. |

This approach ensures requirements remain synchronized and easily editable in both structured and human-friendly formats.

Example:

1. A ReqText item stored in the .reqt.json:

{
    "reqt_ID": "2025-05-20T19:14:37.669Z-12b36284",
    "hier": 1,
    "outline": "5.3",
    "title": "Example Reqt",
    "requirement": "An example must exist for the README generation. It must follow these steps:\n - Create the example in the Tree Editor\n - Write the text in the .reqt.md workflow\n - checked in to the .reqt.json\n - Generated to the README.md and exluded from the README_AI.reqt.json",
    "acceptance": "The example must be clear and helpful. The example must be approved by Joe.",
    "details": "For the README there will be a section to show an example of the .reqt.json, .reqt.md and the generated README.md and README_AI.reqt.json.",
    "readme": "This example demonstrates how a requirement is represented and managed in ReqText, including its appearance in the .reqt.json, .reqt.md, and the generated README files. Use this as a reference for structuring your own requirements and documentation workflow.\n\n\n\n> **A Note from Joe** My workflow is to write all the details in common language, like a prompt, and have AI populate the rest. Then I clean up or change the README section. I did it for this example.",
    "readme_ai": "exclude",
    "test_exists": "true",
    "test_passed": "false",
    "status": "IN DEV"
  }

2. The temporary markdown file created by the out-md command will look like this:

This can be saved as a PDF or your choice for a snap shot of the current state of the project.

-- ReqText ID Comment line - start --

### 5.3: Example Reqt

-- ReqText Table Comment Line--
| Status | Test Exists | Test Passed |
|--------|-------------|-------------|
| IN DEV | true | false |
-- ReqText Table Comment Line--

-- ReqText Requirement Field--
**Requirement:**

 An example must exist for the README generation. It must follow these steps:
 - Create the example in the Tree Editor
 - Write the text in the .reqt.md workflow
 - checked in to the .reqt.json
 - Generated to the README.md and exluded from the README_AI.reqt.json

**Acceptance:**

 The example must be clear and helpful. The example must be approved by Joe.

-- ReqText Details Field--
**Details:**

 For the README there will be a section to show an example of the .reqt.json, .reqt.md and the generated README.md and README_AI.reqt.json.

-- ReqText README Field--
**README:**

This example demonstrates how a requirement is represented and managed in ReqText, including its appearance in the .reqt.json, .reqt.md, and the generated README files. Use this as a reference for structuring your own requirements and documentation workflow.

> **A Note from Joe** My workflow is to write all the details in common language, like a prompt, and have AI populate the rest. Then I clean up or change the README section. I did it for this example.

 
**README AI:**

exclude

-- Make Content "exclude" to exclude from README AI generation --

-- ReqText ID Comment Line --end--

Note: The -- ReqText ID Comment line -- is a comment line that is used for parsing. They include the reqt_id and other metadata. I couldn't put real lines in the example or they would have been stripped out at generation. I hope you get the idea!

3. The README.md file generated by the generate-readme command will look like this:

5.3: Example Reqt

This example demonstrates how a requirement is represented and managed in ReqText, including its appearance in the .reqt.json, .reqt.md, and the generated README files. Use this as a reference for structuring your own requirements and documentation workflow.

A Note from Joe My workflow is to write all the details in common language, like a prompt, and have AI populate the rest. Then I clean up or change the README section. I did it for this example!

README and README_AI Generation

| Command | Description | | --- | --- | | generate-readme, -grm | Generate README.md from the .reqt.json source of truth | | generate-readme_ai, -grmai| Generate README_AI.reqt.json for AI from the .reqt.json source of truth |

The generation is driven by the README and README_AI fields in the .reqt.json. The text exclude will strip the context from the respective file generation.

A Note from Joe My workflow is if I want to include it in both the README and README_AI, I simply have the readme_ai field say "include" and have the AI read the README field. It will still parse the information with the correct ReqText Title and other data. I'd love to hear what you come up with!

init <project name>

Project name can be entered in "" or with spaces, the init command will replace spaces with underscores.

The init command will create a .reqt directory in your root that will hold the following files: - config.reqt.json - The config file for the project - itemTemplate.reqt.json - The template for new items. This can be edited at any time, but will not back populate existing items. - .reqt.json - The source of truth for the project. This is where all the requirements, acceptance, details, and status are stored.

ReqText Tree Editor

Terminal Editor

The terminal editor provides an interactive tree view to create, navigate, and structure your .reqt items. It's the primary interface for building your requirement hierarchy quickly and visually.

Sample Output from reqt editor

    0: ReqText_Demo - In Dev
    ├── 0.1: Design Level Reqts - DESIGN
    ├── 0.2: Instructs Level - INSTRUCT
    ├── 1: Feature 1 - In Dev
    │   ├── 1.1: Requirement 1 - In Dev
    │   └── 1.2: Requirement 2 - ACCEPT
    │       └── 1.2.1: Design Detail - DESIGN
    └── 2: Feature 2 - NEW

Terminal Editor Keybindings

| Key | Action | | -------------- | ------------------------------- | | ↑ / ↓ | Navigate requirements | | k / j | Move item up/down | | → / ← | Demote/Promote (indent/outdent) | | a | Add new item after current | | d | Delete selected item | | e | Edit item title | | r | Reload data | | q / Ctrl+C | Quit and clear console |

Generated by ReqText v0.1.0-demo.21 on 2025-05-24T00:10:21.602Z

ReqText Github Repo