Skip to content

Command Structure & Metadata

This chapter describes how the bash-cli project organizes commands and their associated metadata, enabling a clear and consistent structure for your CLI application. Imagine you are building a CLI tool to manage your projects. You want to have various commands like project create, project list, and project delete. This chapter explains how bash-cli structures these commands and their accompanying help documentation within your project.

Key Concepts

Command Organization

The bash-cli framework uses a directory and file structure within the app/ directory to represent your CLI's commands. Each command, or subcommand, corresponds to an executable script file. This structure mirrors the way you would call the command from the terminal. For instance, the command project create would be represented by the executable file app/project/create. This allows for a logical and intuitive organization of your CLI commands.

Metadata Files

Along with the command scripts, bash-cli utilizes metadata files to store essential information about each command. These files are located alongside the command script and follow a specific naming convention:

  • <command_name>.help: Contains detailed help information for the command. This file is used to generate the help output when the user requests it (e.g., by using the --help flag or calling help <command>).
  • <command_name>.usage: Provides a concise summary of the command's arguments. This is useful for quick reference and is displayed in the help output.

Directories can also contain a .help file to provide category-level help. This allows you to group related commands and offer a high-level overview of their functionality.

Creating and Removing Commands

The create and rm commands are used to manage the command structure and associated metadata files. Let's walk through a simple example of creating the project create command mentioned earlier.

Creating a Command

./bash-cli create project create

This command will:

  1. Create the app/project/ directory if it doesn't exist.
  2. Create a placeholder .help file within the app/project/ directory.
  3. Create the executable script app/project/create.
  4. Create the app/project/create.usage and app/project/create.help files.

The generated create script, .usage, and .help files will contain boilerplate content that you can customize.

Removing a Command

To remove the project create command:

./bash-cli rm project create

This will delete the app/project/create, app/project/create.usage, and app/project/create.help files.

Internal Implementation

The create and rm commands manipulate the file system to create or delete the command structure. Command Dispatcher and Help Generation utilize this structure to execute commands and display help information respectively.

sequenceDiagram
    participant User
    participant Dispatcher
    participant create/rm
    participant File System

    User->>Dispatcher: ./bash-cli create project create
    Dispatcher->>create/rm: Execute create command
    create/rm->>File System: Create files/directories
    File System->>create/rm: Confirmation
    create/rm->>Dispatcher: Success/Failure
    Dispatcher->>User: Output

The relevant code for handling this structure resides in app/command/create.sh and app/command/rm.sh. Here are simplified snippets showcasing the core logic:

app/command/create.sh (simplified):

# ... (Project validation)

CMD_DIR="$APP_DIR/$*"  # Construct the full command directory path

# ... (Create directories and files)

echo "TODO: Implement this command" > "$CMD_DIR/${!#}" # Create command script
# ... (Create .usage and .help files)

This snippet demonstrates how the create command constructs the directory path and creates the necessary files.

app/command/rm.sh (simplified):

# ... (Project Validation)
CMD_DIR="$APP_DIR/$*"  # Construct the full command directory path

# ... (Check if command exists)

rm -f "$CMD_DIR/${!#}" # Remove the command script
# ... (Remove .usage and .help files)

This snippet shows how the rm command locates and removes the command files.

Conclusion

This chapter outlined the core principles of command structure and metadata management in bash-cli. By understanding how commands are organized and how metadata is used, you can effectively manage and document your CLI applications. For a deeper dive into how commands are executed based on this structure, continue to the Command Dispatcher.

Generated by AI Codebase Knowledge Builder