duq CLI

A command-line interface tool for interacting with Amazon Q using different prompt templates.

Features

• Generate README files for project directories
• Get detailed explanations of code files
• Receive refactoring suggestions for your code
• Generate test cases for your code
• Generate documentation for your code
• Run a security analysis on your code
• Command chaining
• Revert unwanted changes made with duq

Prerequisites

Before using duq CLI, you will need to:

1. Install the Amazon Q CLI
2. Authenticate with your Amazon Builder ID

Installing Amazon Q CLI

Follow the official instructions at Amazon Q Developer Guide.

In short:

# For npm users
npm install -g @aws/amazon-q-cli

# For macOS users with Homebrew
brew install amazon-q-cli

Authenticating with Amazon Builder ID

After installing the Amazon Q CLI, authenticate with:

q login

This will open a browser window where you can sign in with your Amazon Builder ID.

Installation

Global Installation (Recommended)

npm install -g duq-cli

Local Installation

npm install duq-cli

Usage

Generate a README for a Directory

duq document ./my-project

With custom output location:

duq document ./my-project -o ./custom-location/README.md

This will:

1. Analyze all files in the directory
2. Generate a comprehensive README.md
3. Save it to the specified directory or custom location

Explain a Code File

duq explain ./my-project/src/index.js

This will provide a detailed explanation of what the code does, its key functions, patterns used, and potential improvements.

Get Refactoring Suggestions

duq refactor ./my-project/src/complex-function.js

This will analyze your code and suggest improvements for code quality, performance, and best practices.

Generate Tests for a File

duq test ./my-project/src/utils.js

With custom output location:

duq test ./my-project/src/utils.js -o ./custom-tests/utils.test.js

This will generate comprehensive test cases for your code and save them to a test file at the default or specified location.

Add Docstrings to Code

Automatically add documentation comments to functions and classes:

duq docstrings ./my-project/src/utils.js

This will:

1. Analyze the code file
2. Generate appropriate docstrings for all functions, classes, and methods
3. Insert the docstrings while preserving the existing code
4. Create a backup of the original file

Security Analysis

Scan your code for security vulnerabilities:

duq security ./my-project

This will:

1. Analyze your code for potential security issues
2. Identify vulnerabilities like injection risks, hardcoded secrets, etc.
3. Provide severity ratings and remediation suggestions
4. Optionally save a detailed report

You can also analyze a single file:

duq security ./my-project/server.js --output security-report.md

Command Chaining

Run multiple commands in sequence:

duq chain ./my-project/src/utils.js "refactor,test,docstrings"

This will:

1. First refactor the code for better quality
2. Then generate tests for the refactored code
3. Finally add docstrings to all functions

You can use the --continue-on-error flag to ensure all steps are attempted even if some fail:

duq chain ./my-project/src/api.js "refactor,test,docstrings" --continue-on-error

Chain commands work with both files and directories (though some commands like document only work with directories, and others like docstrings only work with files).

Backup and Revert

DUQ CLI automatically creates backups of files before modifying them. You can revert to previous versions:

Revert the Most Recent Change

duq revert

This will undo the most recent file modification made by DUQ CLI.

Revert a Specific File

duq revert ./my-project/src/utils.js

This will restore the file to its state before the most recent DUQ CLI operation.

List Available Backups

duq backups

This will show all available backups across all files.

List Backups for a Specific File

duq backups ./my-project/src/utils.js

This will show the backup history for a specific file.

Restore a Specific Backup

duq revert ./my-project/src/utils.js --id backup-id-from-list

This will restore the file to the state of the specified backup.

Examples

# Generate a README for a React project
duq document ./my-react-app

# Generate a README and save it to a specific location
duq document ./my-react-app -o ./docs/README.md

# Explain a complex algorithm
duq explain ./algorithms/quicksort.js

# Get refactoring suggestions for a utility file
duq refactor ./utils/data-processing.js

# Generate tests for an API endpoint
duq test ./api/users.js

# Generate tests and save them to a specific location
duq test ./api/users.js -o ./tests/api/users.test.js

How It Works

duq CLI works by:

1. Reading your code files or directories
2. Formatting the content with specialized prompts
3. Sending the prompts to Amazon Q through the official CLI
4. Processing and displaying the responses
5. Amazon Q saves the output to files at the specified locations

Troubleshooting

Authentication Issues

If you encounter authentication issues:

# Re-authenticate with Amazon Q
q login

Command Not Found

If the duq command is not found:

# Check if the package is installed globally
npm list -g duq-cli

# If not, install it globally
npm install -g duq-cli

Amazon Q CLI Not Found

If you get an error about Amazon Q CLI not being installed:

# Install Amazon Q CLI
npm install -g @aws/amazon-q-cli

# Then authenticate
q login

Verify Amazon Q Installation

To verify that Amazon Q CLI is properly installed:

# Check the installed version
q --version

Diagnose Amazon Q Issues

If you're experiencing problems with Amazon Q:

# Run the built-in diagnostics
q doctor

This will check your installation, authentication, and connectivity.

Requirements

• Node.js 14 or higher (for npm installation)
• Amazon Q CLI
• Amazon Builder ID