playbooks

home / skills / dimitrigilbert / parsearger / parsearger-utils

parsearger-utils skill

/skills/parsearger-utils

This skill scaffolds new CLI projects, generates documentation, creates completion scripts, and builds HTML forms to jumpstart development.

npx playbooks add skill dimitrigilbert/parsearger --skill parsearger-utils

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
4.3 KB
---
name: parsearger-utils
description: Utilities for parseArger. Use this skill for PROJECT scaffolding, DOCUMENTATION generation, COMPLETION scripts, and HTML FORMS.
license: MIT
compatibility: Requires parseArger executable.
---

# ParseArger Utilities

This skill provides tools for managing full projects, generating documentation, bash completion, and web forms.

## Invocation Rules

1. Check `which parseArger` → if found, use `parseArger`
2. Fallback: `./parseArger` (in project root)
3. Never assume location - always check first

---

## 1. Project Scaffolding (`project`)

Create a full directory structure for a new CLI tool, including subcommands, tests, and documentation support.

```bash
parseArger project NAME [OPTIONS]
```

**Options:**
- `--description "DESC"`: Project description.
- `--project-subcommand "NAME"`: Create specific subcommands (repeatable).
- `--directory "DIR"`: Output directory (default `./NAME`).
- `--git-repo "USER/REPO"`: Set git repository URL.
- `--installer-git-service "HOST"`: Git host (default `github.com`).
- `--no-readme`: Skip README generation.
- `--no-git`: Skip `git init`.

#### Example: Full CLI Tool Setup

```bash
# Create a complex tool with multiple subcommands
parseArger project mdd \
  --description "Markdown tools for my blog" \
  --git-repo "DimitriGilbert/mdd" \
  --project-subcommand article \
  --project-subcommand build \
  --project-subcommand deploy
```

This generates:
- `mdd/bin/article` (and others)
- `mdd/mdd.rc` (source this to setup aliases)
- `mdd/documentation.md`
- `mdd/completely.yaml`

---

## 2. Bash Completion (`completely`)

Generate bash completion scripts and configuration using `completely` library.

```bash
parseArger completely COMMAND-NAME SCRIPT-FILE [OPTIONS]
```

**Dependency**: Requires the `completely` Ruby gem OR Docker installation. Use `--completely-cmd` to specify a custom command (e.g., via Docker).

**Options:**
- `--subcommand-directory "DIR"`: Scan directory for subcommands to include in completion.
- `--completion-file "FILE"`: Output bash script (default `completely.bash`).
- `--yaml-file "FILE"`: Output intermediate YAML config (default `completely.yaml`).
- `--run-completely`: Run the generator (default on). Use `--no-run-completely` to only output YAML.
- `--completely-cmd "CMD"`: Custom command to run `completely` (e.g. via Docker).

#### Example

```bash
parseArger completely my-tool ./bin/my-tool --subcommand-directory ./bin
```

---

## 3. Documentation (`document`)

Generate Markdown documentation from argument definitions.

```bash
parseArger document [OPTIONS]
```

**Options:**
- `--file "FILE"`: File to document (repeatable).
- `--directory "DIR"`: Document all scripts in directory (repeatable).
- `--out "FILE"`: Output file (stdout if omitted).
- `--append-output`: Append to existing file (default on).
- `--title "TITLE"`: Main title (default "Usage").
- `--tag "##"`: Markdown tag level.

#### Example

```bash
parseArger document --directory ./bin --out DOCUMENTATION.md
```

---

## 4. HTML Forms (`html-form`)

Generate a standalone HTML form that maps to the CLI arguments. Useful for web interfaces.

**Output**: Generates an HTML file you can open in a browser. The form lets users interactively build command-line arguments.

```bash
parseArger html-form FILE [OPTIONS]
```

**Options:**
- `--out "FILE"`: Output HTML file.
- `--command "CMD"`: The command string to build (defaults to filename).
- `--action "URL"`: Form action URL.
- `--js` / `--no-js`: Generate JavaScript for dynamic command building (default on).
- **Styling (Bootstrap defaults):**
  - `--form-class`, `--input-class`, `--label-class`
  - `--checkbox-class`, `--select-class`, etc.

#### Example

```bash
parseArger html-form ./bin/my-script --out form.html
```

---

## 5. Bulk Parse (`bulk-parse`)

Perform operations on multiple files at once.

```bash
parseArger bulk-parse [OPTIONS]
```

**Options:**
- `--file "FILE"`, `--directory "DIR"`.
- `--bump "VERSION"`: Bump version number across all files.

#### Examples

```bash
# Bump version to 2.0.0 across multiple specific files
parseArger bulk-parse --file bin/script1.sh --file bin/script2.sh --bump "2.0.0"

# Bump version across all scripts in a directory
parseArger bulk-parse --directory ./bin --bump "1.5.0"

# Bump version across multiple directories
parseArger bulk-parse --directory ./bin --directory ./scripts --bump "3.0.0"
```

Overview

This skill provides utilities for working with parseArger-based CLIs: project scaffolding, documentation generation, bash completion, HTML form generation, and bulk operations. Use it to bootstrap a CLI project, produce user-facing docs, emit completion scripts, create web forms that map to CLI arguments, and perform batch edits across many scripts. It integrates with external tools like the completely gem or Docker when needed.

How this skill works

The utilities inspect parseArger argument definitions in script files or directories and generate outputs (files, YAML, HTML, or completion scripts) accordingly. Invocation prefers a system-wide parseArger binary if present, otherwise it falls back to a local ./parseArger in the project root. Commands accept file and directory inputs, output targets, and flags that control runtime behavior such as running the completion generator or emitting JS for web forms.

When to use it

  • Starting a new CLI project and needing a full scaffold with subcommands, tests, and docs.
  • Generating Markdown usage documentation from existing script argument definitions.
  • Producing bash completion scripts for complex tools using the completely library or Docker.
  • Creating a standalone HTML form so non-technical users can build command lines in a browser.
  • Applying bulk edits like version bumps across many scripts or directories.

Best practices

  • Always run `which parseArger` or ensure a local ./parseArger is present before invoking commands.
  • Keep argument definitions in the executable scripts so document and completion tools can source them.
  • When generating completions, prefer a native completely gem install or provide a Docker-based --completely-cmd.
  • Use --subcommand-directory to include dynamically discovered subcommands in completion output.
  • Review generated YAML or HTML before auto-deploying; use --no-run-completely to produce YAML only for inspection.

Example use cases

  • Bootstrap a new CLI named mytool with article and deploy subcommands and an initial documentation.md.
  • Generate a completely.bash completion script for ./bin/my-tool by scanning the bin directory for subcommands.
  • Document all scripts in ./bin into DOCUMENTATION.md by running the document command on the directory.
  • Create form.html that maps my-script arguments to an interactive web form with JS-enabled command building.
  • Bump the version string to 2.0.0 across multiple scripts by running bulk-parse with --bump and multiple --file flags.

FAQ

What if parseArger is not on my PATH?

The tools will fall back to ./parseArger in the project root. Always check existence before running and supply a local binary if needed.

Do I need the completely Ruby gem to generate completions?

The completely gem is recommended, but you can provide a Docker-based command via --completely-cmd or disable running with --no-run-completely to inspect generated YAML only.