Advanced Usage

qmims is designed to be simple for first-time use, but it also supports more advanced documentation workflows. This page covers the features and patterns that become useful when you want repeatable output, safer automation, or tighter integration with your existing development process.

Dry Run Mode

Dry run mode is the safest way to inspect what qmims intends to do before it changes any files. This is especially useful when you are testing a new template, validating an instruction-driven workflow, or confirming that the correct target file is being used.

qmims generate --dry-run
qmims edit --dry-run

Dry run mode is especially useful for:

• checking the selected generation mode
• confirming the output path before overwriting a file
• verifying fallback README detection in edit workflows
• reviewing automation behavior before using --yes

Verbose Output

Verbose mode prints additional diagnostic information that can help you understand what qmims is doing internally. It is useful when debugging Kiro setup issues, template selection, config defaults, or command behavior.

qmims generate --verbose
qmims edit --verbose

Verbose output can help you inspect:

• Kiro availability and authentication checks
• resolved paths and selected execution modes
• prompt preparation and command flow details
• non-zero exit behavior when Kiro fails

Force Overwrite

When generating a README into a path that already exists, qmims normally prompts before overwriting the file. Use --force when you already know you want to replace the existing output.

qmims generate --force

Automatic Approval

qmims supports an auto-approval flow for Kiro-backed runs. This is useful when you are scripting documentation tasks or running qmims in an environment where you do not want interactive permission prompts.

qmims generate --yes
qmims edit --yes

You can also make this your default behavior through configuration:

qmims config set q.autoApproveEdits true

In the current Kiro-backed workflow, this setting controls whether qmims should automatically enable the documented tool-trust behavior for non-interactive execution.

Custom Output Paths

You are not limited to README.md. If your project uses a different filename or stores docs in a dedicated directory, you can generate there directly.

qmims generate --output docs/PROJECT-README.md

You can also save that preference as a default so you do not need to repeat it:

qmims config set defaults.outputFileName docs/PROJECT-README.md

Template-Driven Workflows

Template mode is one of the most useful advanced features because it lets you standardize README structure across projects while still letting Kiro generate project-specific content.

qmims generate --mode template:detailed
qmims generate --mode template:library
qmims generate --mode template:service

A strong pattern is to pick one template family for a team or repository type and make it the default:

qmims config set defaults.templateName detailed

For more on this, see Working with Templates.

Instruction-Driven Maintenance

One of the best long-term workflows is to generate an initial README, then maintain it with embedded instructions. This gives you more control than fully regenerating the file every time.

# Generate a first draft
qmims generate --mode template:detailed

# Add embedded qmims instructions to selected sections
# Then update only those sections
qmims edit

This works especially well when your README has both stable hand-written content and sections that should evolve with the codebase, such as installation steps, commands, features, or API summaries.

Multi-Instruction Instruct Mode

In instruct mode, qmims now uses all parsed embedded instructions when preparing the Kiro prompt. This makes it much more useful for structured generation across several sections of a file.

qmims generate --mode instruct
qmims generate --mode instruct:README.md

This is a good fit when you want to treat a Markdown file as a generation blueprint rather than as a finished document.

Kiro Authentication for Automation

For local interactive usage, the simplest path is:

kiro-cli login
kiro-cli whoami

For CI or other headless environments, use KIRO_API_KEY:

# Linux / macOS
export KIRO_API_KEY=your_api_key_here

# Windows PowerShell
$env:KIRO_API_KEY = "your_api_key_here"

If something looks wrong with the environment, Kiro's diagnostic commands are the first place to check:

kiro-cli whoami
kiro-cli doctor

Combining Options

qmims flags are designed to be composed. A few common advanced command combinations include:

# Generate a structured README and replace any existing file
qmims generate --mode template:detailed --output docs/README.md --force

# Preview a precise instruct-based workflow
qmims generate --mode instruct:README.md --dry-run

# Run an automated edit pass with detailed logs
qmims edit docs/README.md --yes --verbose

CI / Script-Friendly Usage

qmims works well in scripted documentation workflows as long as you are explicit about authentication and approvals. A practical automation pattern is:

1. set up Kiro authentication with KIRO_API_KEY
2. run a dry-run pass while building the workflow
3. switch to --yes only when the behavior is already validated
4. commit generated changes using your normal Git process

Suggested Advanced Workflow

# 1. Verify Kiro
kiro-cli whoami

# 2. Configure defaults
qmims config set defaults.templateName detailed
qmims config set defaults.outputFileName README.md

# 3. Preview the workflow
qmims generate --dry-run

# 4. Generate the first README
qmims generate --mode template:detailed

# 5. Add embedded instructions for sections you want to keep current
# 6. Update those sections over time
qmims edit --dry-run
qmims edit

This approach gives you a maintainable balance between automation and editorial control.

Related Docs

• Generate Command
• Edit Command
• Configuration System
• Embedded Instructions