docs: implement CLI configuration guide

.changeset/docs-config-guide.md

@@ -0,0 +1,5 @@
+---
+"@asyncapi/cli": patch
+---
+
+docs: implement CLI configuration guide

docs/commands/generate.md

@@ -0,0 +1,73 @@
+
+
+# asyncapi generate
+
+Generates code from AsyncAPI documents using AsyncAPI Generator templates.
+
+## Description
+
+The `asyncapi generate` command generates code from AsyncAPI documents using AsyncAPI Generator templates. This allows developers to quickly implement API clients, servers, documentation, and more based on their AsyncAPI specifications.
+
+The command supports three main subcommands:
+
+1. **Generate from template**: `asyncapi generate fromTemplate <asyncapi-spec> <template>`
+2. **Generate models**: `asyncapi generate models <asyncapi-spec>`
+3. **Generate client**: `asyncapi generate client <language> <asyncapi-spec>`
+
+## Common Options
+
+### For all subcommands:
+
+- `--output, -o <directory>`: Specify the output directory for generated code
+- `--install`: Install the template and its dependencies
+- `--force-write`: Force writing of generated files even if the output directory is not empty
+- `--param, -p <key=value>`: Additional parameters to pass to the template
+- `--map-base-url`: Maps all schema references from base URL to local folder
+- `--registry-url`: Specifies the URL of the private registry for fetching templates
+- `--registry-auth`: The registry username and password encoded with base64
+- `--registry-token`: The npm registry authentication token
+- `--no-interactive`: Disable interactive mode and run with provided flags
+- `--debug`: Enable more specific errors in the console
+
+## Common Flags
+
+| Flag | Description |
+|------|-------------|
+| `--output, -o` | Directory where generated code will be saved |
+| `--install` | Install the template and its dependencies |
+| `--force-write` | Force writing of generated files |
+| `--param, -p` | Additional parameters to pass to the template |
+| `--map-base-url` | Maps all schema references from base URL to local folder |
+| `--registry-url` | Specifies the URL of the private registry |
+| `--registry-auth` | The registry username and password encoded with base64 |
+| `--registry-token` | The npm registry authentication token |
+| `--no-interactive` | Disable interactive mode |
+| `--debug` | Enable more specific errors |
+
+## Examples
+
+1. Generate models from AsyncAPI specification:
+   ```bash
+   asyncapi generate models spec.yaml
+   ```
+
+2. Generate client for a specific language:
+   ```bash
+   asyncapi generate client javascript spec.yaml --param version=1.0.0 --output ./client
+   ```
+
+3. Generate code from template with specific parameters:
+   ```bash
+   asyncapi generate fromTemplate spec.yaml @asyncapi/html-template --param version=1.0.0 --output ./docs
+   ```
+
+4. Generate code with force-write option:
+   ```bash
+   asyncapi generate fromTemplate spec.yaml @asyncapi/html-template --force-write --output ./generated
+   ```
+
+5. Generate code with registry configuration:
+   ```bash
+   asyncapi generate fromTemplate spec.yaml @asyncapi/html-template --registry-url https://custom-registry.com --registry-token mytoken
+   ```
+

docs/configuration-guide.md

@@ -0,0 +1,171 @@
+
+# AsyncAPI CLI Configuration Guide
+
+This guide explains how to use the `asyncapi config` command to manage configuration settings for the AsyncAPI CLI.
+
+## Overview
+
+The `asyncapi config` command provides several subcommands to manage different aspects of the CLI configuration:
+
+- **`config`**: Main configuration command
+- **`config analytics`**: Manage analytics settings
+- **`config auth add`**: Add authentication configurations
+- **`config context`**: Manage context configurations (short aliases for AsyncAPI documents)
+- **`config versions`**: Show versions of AsyncAPI tools used
+
+## Using the `asyncapi config` Command
+
+### 1. Managing Analytics Settings
+
+The AsyncAPI CLI collects anonymous usage analytics to improve the product. You can enable, disable, or check the current status of analytics:
+
+```bash
+# Enable analytics
+asyncapi config analytics --enable
+
+# Disable analytics
+asyncapi config analytics --disable
+
+# Check current analytics status
+asyncapi config analytics --status
+```
+
+### 2. Managing Authentication Configurations
+
+Add authentication configurations for resolving $ref files that require HTTP Authorization:
+
+```bash
+# Add authentication configuration
+asyncapi config auth add PATTERN TOKEN [--auth-type AUTH_TYPE] [--header HEADER]
+
+# Example: Add GitHub authentication
+asyncapi config auth add "github.com/**/*.*" $GITHUB_TOKEN --auth-type Bearer
+```
+
+**Flags:**
+- `--auth-type`: Authentication type (default is "Bearer")
+- `--header`: Additional header in key=value format (can be used multiple times)
+
+### 3. Managing Context Configurations
+
+Context configurations allow you to create short aliases for full paths to AsyncAPI documents, making it easier to work with multiple specifications.
+
+#### Initialize Context Configuration
+
+```bash
+# Initialize context configuration in the current directory
+asyncapi config context init
+
+# Initialize context configuration in the root of the current repository
+asyncapi config context init ./
+
+# Initialize context configuration in the user's home directory
+asyncapi config context init ~
+
+# Initialize context configuration in a specific directory
+asyncapi config context init /path/to/directory
+```
+
+#### Add a New Context
+
+```bash
+# Add a new context
+asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH
+
+# Example: Add a context named "my-api" pointing to an AsyncAPI spec
+asyncapi config context add my-api ./asyncapi.yaml
+
+# Set the context being added as the current context
+asyncapi config context add my-api ./asyncapi.yaml --set-current
+```
+
+#### List All Contexts
+
+```bash
+# List all stored contexts
+asyncapi config context list
+```
+
+#### View Current Context
+
+```bash
+# Show the current context that is being used
+asyncapi config context current
+```
+
+#### Use a Specific Context
+
+```bash
+# Set a context as current
+asyncapi config context use CONTEXT-NAME
+
+# Example: Use the "my-api" context
+asyncapi config context use my-api
+```
+
+#### Edit a Context
+
+```bash
+# Edit an existing context
+asyncapi config context edit CONTEXT-NAME NEW-SPEC-FILE-PATH
+
+# Example: Update the "my-api" context with a new spec file
+asyncapi config context edit my-api ./new-asyncapi.yaml
+```
+
+#### Remove a Context
+
+```bash
+# Delete a context from the store
+asyncapi config context remove CONTEXT-NAME
+
+# Example: Remove the "my-api" context
+asyncapi config context remove my-api
+```
+
+### 4. Viewing Tool Versions
+
+```bash
+# Show versions of AsyncAPI tools used
+asyncapi config versions
+```
+
+## Configuration File Location
+
+The configuration files are stored in the following locations:
+
+- **Context files**: Stored in `.asyncapi-cli` file in the current directory, repository root, or user's home directory. The CLI automatically searches for this file in the following locations:
+  - Current directory: `.asyncapi-cli`
+  - Repository root: `.asyncapi-cli`
+  - User's home directory: `~/.asyncapi-cli`
+
+- **Authentication configurations**: Stored in the same `.asyncapi-cli` file as context configurations (JSON format)
+- **Analytics settings**: Stored in the same `.asyncapi-cli` file as context configurations (JSON format)
+
+## Best Practices
+
+1. **Use contexts** to manage multiple AsyncAPI specifications in your projects
+2. **Set a default context** using the `--set-current` flag when adding new contexts
+3. **Use environment variables** for sensitive tokens in authentication configurations
+4. **Check analytics status** periodically to ensure you're comfortable with the data collection
+
+## Troubleshooting
+
+If you encounter issues with configuration:
+- Verify the configuration file locations
+- Check file permissions
+- Ensure you're using the latest version of the AsyncAPI CLI
+- Check the CLI logs for detailed error messages
+
+## Summary
+
+The AsyncAPI CLI provides powerful configuration options to customize your workflow. The `asyncapi config` command allows you to:
+- Manage analytics settings
+- Configure authentication for protected resources
+- Create and manage context aliases for AsyncAPI documents
+- View tool versions
+
+This configuration system helps you maintain a consistent and efficient workflow when working with multiple AsyncAPI specifications.
+
+---
+Completed configuration guide for [asyncapi/cli]