clean: updated README

Author: alerizzo

README.md

@@ -1,117 +1,218 @@
-# codacy-cli-v2
+# Codacy CLI v2
 
-The Codacy CLI (version 2) is a command-line tool that supports analyzing code using tools like ESLint and uploading the results in SARIF format to Codacy. 
-The tool is invoked using the `codacy-cli` command, and provides two main commands: analyze and upload.
+Codacy CLI (version 2) is a command-line tool for running code analysis and integrating with Codacy. If your repository exists in Codacy, you can sync your configuration to ensure consistency with your organization's standards. 
 
-### Commands
+You can also use Codacy CLI for local code analysis without a Codacy account, leveraging the linter configuration files found in your project's root.
 
-- **`analyze` Command**: Runs ESLint analysis on the codebase.
-    - `--output, -o`: Output file for the results.
-    - `--tool, -t`: Specifies the tool to run analysis with (e.g., ESLint).
-    - `--format`: Output format (use 'sarif' for SARIF format to terminal).
-    - `--fix`: Automatically fixes issues when possible.
+The CLI supports uploading analysis results (in [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) format) to Codacy as well.
 
-- **`upload` Command With Project Token**: Uploads a SARIF file containing analysis results to Codacy.
-    - `--sarif-path, -s`: Path to the SARIF report.
-    - `--commit-uuid, -c`: Commit UUID.
-    - `--project-token, -t`: Project token for Codacy API.
+It is invoked using the `codacy-cli` command and provides several commands for project setup, analysis, and integration.
 
-- **`upload` Command With API Token**: Uploads a SARIF file containing analysis results to Codacy.
-    - `--sarif-path, -s`: Path to the SARIF report.
-    - `--commit-uuid, -c`: Commit UUID.
-    - `--api-token, -a`: User level token for Codacy API.
-    - `--provider, -p`: Provider name (e.g., gh, gl, bb).
-    - `--owner, -o`: Repository owner.
-    - `--repository, -r`: Repository name.
+---
 
-### Important Concepts
+## Supported Platforms
 
-- **`.codacy/codacy.yaml`**: Configuration file to specify runtimes and tools versions for the CLI.
-  ```yaml
-  runtimes:
-      - [email protected]
-  tools:
-      - [email protected]
-  
-- **`codacy-cli install`**: Command to install the specified node and eslint versions before running analysis.
+- **macOS**
+- **Linux**
+- **Windows (via WSL only)**
 
-## Download
+> **Note:** Native Windows is not yet supported. For Windows, use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/) and follow the Linux instructions inside your WSL terminal.
 
-### MacOS (brew)
+---
 
-To install `codacy-cli` using Homebrew:
+## Installation
+
+### macOS (Homebrew)
 
 ```bash
 brew install codacy/codacy-cli-v2/codacy-cli-v2
 ```
 
-### Linux
+### Linux / Windows (WSL)
 
-For Linux, we rely on the codacy-cli.sh script in the root. To download the CLI, run:
+Run the following in your terminal (Linux or WSL):
 
 ```bash
 bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)
 ```
-You can either put the downloaded script in a specific file or create an alias that will download the script and look for changes:
+
+Or create an alias for convenience:
 
 ```bash
 alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)"
 ```
 
-## Installation
+---
+
+## CLI Commands
+
+### `init` — Bootstrap Project Configuration
 
-Before running the analysis, install the specified tools:
+Bootstraps the CLI configuration in your project's folder. This command creates a `.codacy` directory containing a `codacy.yaml` file, which specifies the runtimes and tools that will be used and installed.
+
+- If you provide Codacy repository information (API token, provider, organization, repository), the configuration will be fetched from Codacy, ensuring consistency with your organization's standards.
+- If no Codacy information is provided, all available tools will be included. For each tool, if a local configuration file exists in your project, it will be used; otherwise, an empty configuration file will be created for that tool.
+
+- **Local mode (local configuration files):**
+  ```bash
+  codacy-cli init
+  ```
+- **Remote mode (fetch configuration from Codacy):**
+  ```bash
+  codacy-cli init --api-token <token> --provider <gh|gl|bb> --organization <org> --repository <repo>
+  ```
+
+**Flags:**
+- `--api-token` (string): Codacy API token (optional; enables fetching remote config)
+- `--provider` (string): Provider (`gh`, `gl`, `bb`), required with `--api-token`
+- `--organization` (string): Organization name, required with `--api-token`
+- `--repository` (string): Repository name, required with `--api-token`
+
+### `install` — Install Runtimes and Tools
+
+Installs all runtimes and tools specified in `.codacy/codacy.yaml`:
+- Downloads and extracts runtimes (Node, Python, Dart, Java, etc.)
+- Installs tools (ESLint, Trivy, Pylint, PMD, etc.) using the correct package manager or direct download
+- Handles platform-specific details
+- Skips already installed components (e.g., Node, Python, Dart, Java, etc.)
+- Shows a progress bar and reports any failures
 
 ```bash
 codacy-cli install
 ```
+- Optionally specify a custom registry:
+  ```bash
+  codacy-cli install --registry <url>
+  ```
 
-## Run Analysis
+### `analyze` — Run Code Analysis
 
-To run ESLint and output the results to the terminal:
+Runs all configured tools, or a specific tool, on your codebase.
 
 ```bash
+# Run all tools
+tcodacy-cli analyze
+
+# Run a specific tool (e.g., ESLint)
 codacy-cli analyze --tool eslint
+
+# Output results in SARIF format
+tcodacy-cli analyze --tool eslint --format sarif
+
+# Store results as SARIF in a file
+codacy-cli analyze -t eslint --format sarif -o eslint.sarif
+
+# Analyze a specific file with all configured tools
+codacy-cli analyze path/to/file.js
+
+# Analyze a specific file with a specific tool (e.g., ESLint)
+codacy-cli analyze --tool eslint path/to/file.js
 ```
 
-To output results in SARIF format to the terminal:
+**Flags:**
+- `--output, -o`: Output file for the results; if not provided, results will be printed to the console
+- `--tool, -t`: Tool to run analysis with (e.g., eslint)
+- `--format`: Output format (e.g., `sarif`)
+- `--fix`: Automatically fix issues when possible
+
+### `upload` — Upload SARIF Results to Codacy
+
+Uploads a SARIF file containing analysis results to Codacy.
 
 ```bash
-codacy-cli analyze --tool eslint --format sarif
+# With project token
+codacy-cli upload -s path/to/your.sarif -c <commit-uuid> -t <project-token>
+
+# With API token
+codacy-cli upload -s path/to/your.sarif -c <commit-uuid> -a <api-token> -p <provider> -o <owner> -r <repository>
 ```
 
-To store the results as SARIF in a file:
+**Flags:**
+- `--sarif-path, -s`: Path to the SARIF report (required)
+- `--commit-uuid, -c`: Commit UUID
+- `--project-token, -t`: Project token for Codacy API
+- `--api-token, -a`: User-level token for Codacy API
+- `--provider, -p`: Provider name (e.g., gh, gl, bb)
+- `--owner, -o`: Repository owner
+- `--repository, -r`: Repository name
+
+### `update` — Update the CLI
+
+Fetches and installs the latest version of the CLI.
 
 ```bash
-codacy-cli analyze -t eslint --format sarif -o eslint.sarif
+codacy-cli update
 ```
 
-## Upload Results
+### `version` — Show Version Information
 
-To upload a SARIF file to Codacy:
+Displays detailed version/build information for the CLI.
 
 ```bash
-codacy-cli upload -s path/to/your.sarif -c your-commit-uuid -t your-project-token
+codacy-cli version
 ```
 
-## Breaking Changes
+---
+
+## Configuration
 
-Some behaviors have changed with the new updates of the CLI. To rely on a specific version, you can add that version to your environment:
+- **`.codacy/codacy.yaml`**: Main configuration file specifying runtimes and tool versions.
+- **`.codacy/tools-configs/`**: Tool-specific configuration files (auto-generated or fetched from Codacy).
 
+---
+
+## Example Usage
+
+```bash
+# 1. Initialize project (local or remote)
+codacy-cli init
+# or
+codacy-cli init --api-token <token> --provider gh --organization my-org --repository my-repo
+
+# 2. Install all required runtimes and tools
+codacy-cli install
+
+# 3. Run analysis (all tools or specific tool)
+codacy-cli analyze
+codacy-cli analyze --tool eslint
+
+# 4. Upload results to Codacy
+codacy-cli upload -s eslint.sarif -c <commit-uuid> -t <project-token>
 ```
-export CODACY_CLI_V2_VERSION="1.0.0-main.133.3607792"
+
+---
+
+## Troubleshooting
+
+### WSL (Windows Subsystem for Linux)
+- **Always use a WSL terminal** (e.g., Ubuntu on Windows) for all commands.
+- Ensure you have the latest version of WSL and a supported Linux distribution installed.
+- If you see errors related to missing Linux tools (e.g., `curl`, `tar`), install them using your WSL package manager (e.g., `sudo apt install curl tar`).
+
+### MacOS: Errors related to `docker-credential-osxkeychain` not found
+
+Install the docker credential helper:
+
+```bash
+brew install docker-credential-helper
 ```
 
+---
+
 ## Example Repository
 
-As an example, you can check https://github.com/troubleshoot-codacy/eslint-test-examples for a repository that has an action relying on this CLI.
+See [eslint-test-examples](https://github.com/troubleshoot-codacy/eslint-test-examples) for a repository using this CLI in GitHub Actions.
 
-## Troubleshooting
+---
 
-#### Errors related to `docker-credential-osxkeychain` not found when running analysis
+## Breaking Changes & Version Pinning
 
-Install the docker credential helper. For example, in MacOS:
+Some behaviors have changed with recent updates. To rely on a specific CLI version, set the following environment variable:
 
 ```bash
-brew install docker-credential-helper
+export CODACY_CLI_V2_VERSION="1.0.0-main.133.3607792"
 ```
+
+Check the [releases](https://github.com/codacy/codacy-cli-v2/releases) page for all available versions.
+
+---