DevSecOps Engineer, Author, and Mentor

In a post on Documentation and AI , I advocated for the use of Doxygen-style comments when developing and maintaining shell scripts to preserve intent, contracts, interfaces, edge-cases, and context information. An AI wouldn't need to reinterpret how a block of Bash shell script code worked every time it ran. Doing so would provide a pathway by which subtle changes in understanding could be introduced, much like what happens in a telephone game.

Another benefit of that structured documentation technique is the ability to generate usage information for shell scripts. This allows you to automatically generate what is displayed when someone runs your_script.bash --help without having to maintain that help screen yourself.

So, I put together a tool that can accept one or more Bash shell scripts as inputs, generate the help text, and then inject that help text back into the script. Along the way, the incoming Bash shell scripts are minimized so that the finished version is tighter and no longer carries the full volume of inline documentation.

Since my scripts typically have two lines of comments for every line of code, this results in shipped scripts having about one-third the size of the heavily-documented versions.

This tooling -- which can be run via Docker or installed directly -- is intended for use in a CI/CD setting. I write something in my_script.src.bash and it produces my_script.bash when a commit is pushed to the upstream repository.

The tool can be found on GitHub at wesley-dean/bash_usage_help_generator or on DockerHub at wesleydean/bash_usage_help_generator

Full Example

This is an example of how the tool works.

Input: example.src.bash

#!/usr/bin/env bash

## @file example.src.bash
## @brief Example CLI tool
## @details
## This script demonstrates usage help generation.
##
while getopts "h" option ; do
  case "$option" in
    h) usage_help ; exit 0 ;; ##- display usage help
  esac
done

printf 'Hello\n'

Run

bash_usage_help_generator.bash example.src.bash

Output: example.bash

#!/usr/bin/env bash
## @cond GENERATED_USAGE_HELP
usage_help() {
  cat <<'__BASHLIB_USAGE_HELP__'
## Usage

`example.bash` [-h]

# file example.src.bash

## Brief

Example CLI tool

## Details

This script demonstrates usage help generation.

## Options

* `-h`: display usage help

__BASHLIB_USAGE_HELP__
}
## @endcond
while getopts "h" option ; do case "$option" in h) usage_help ; exit 0 ;;esac;done;printf 'Hello\n';

Explanation

The tool takes the original script, example.src.bash, extracts the comments, and then writes example.bash to the same directory as example.src.bash. The written file is minified -- which isn't very obvious in this example -- and has the help text injected near the top of the script.

Resources

I also recommend adding the following to your Bash shell scripting pipelines:

• shellcheck: Bash linting
• shfmt: automatic formatting
• bats: Bash unit testing
• Bash Minifier: compact Bash scripts

Read More

The first time I seriously considered using artificial intelligence in my professional work, the answer was already decided.

No.

The decision was not mine to make. At the time, I was working on federal projects with significant security and compliance requirements. Public large language models (LLMs) were prohibited. That meant that we couldn't paste source code into prompts, upload documentation, or use project artifacts as context for retrieval systems. Even projects built largely upon open-source software were subject to the same restrictions. While developers across the industry were experimenting with AI-assisted coding, summarization, and research, our path was considerably narrower. The technology was simply too new, and too many questions remained unanswered.

At the time, I viewed those restrictions primarily as a security matter. That was certainly how most discussions were framed. Once information leaves a system, control becomes difficult to maintain. Data can be copied, logged, replicated, retained, backed up, and transferred in ways that are not always visible to the person who originally submitted it. A vendor might truthfully state that information would not be used for model training while still leaving dozens of important questions unresolved. Where would the data be stored? Who would have access to it? How long would it remain? What protections existed against misuse? These were practical questions, and they deserved practical answers.

Yet over time I began to notice something interesting. Security perspectives explained much of the concern, but not all of it. Compliance perspectives explained some of it. Risk management perspectives explained some of it. Data governance perspectives explained some of it. Each framework illuminated part of the picture, yet none seemed capable of explaining why the issue felt important even in situations where no obvious harm existed. A public document submitted to an AI system might contain no secrets, and an open-source repository might contain no protected information. A conference presentation might already be available to anyone willing to watch it online. The discomfort remained.

That lingering discomfort eventually led me to a question I had not considered before. What exactly was I trying to protect?

Read More

Artificial intelligence has made old questions feel newly urgent.

We can now collect, store, analyze, imitate, synthesize, and reproduce human expression at a scale that would have been difficult to imagine only a few years ago. A photograph can become image data. A voice can become a sample. A body of writing can become a statistical pattern. A lifetime of work can become material for a system that learns, imitates, and responds.

The legal questions matter. Who owns the data? Who may train on it? What does a license permit? What do terms of service allow? Where does fair use begin and end?

Yet this series is concerned with a deeper set of questions.

When does our desire to benefit from another person begin to eclipse our obligation to respect them?

What does genuine consent look like when information can be copied, retained, recombined, and transformed indefinitely?

Does public availability imply permission?

Does usefulness create entitlement?

Can a system learn from a person's work without beginning to appropriate the person behind it?

What happens when AI moves from learning from someone to speaking as someone?

These essays explore consent as more than a legal mechanism. Consent is one of the ways we recognize another person's dignity, agency, and right to participate in decisions that affect them. When consent is ignored, bypassed, or reduced to a technical defense, something human begins to disappear.

The question is not merely whether AI can do these things.

It can.

The question is whether our ability to do something relieves us of the responsibility to ask whether we should.

Posts in this Series

1. Consent in the Age of AI (Introduction)
2. Consent in the Age of AI (Part 1)

Read More