@teambit/harmony.content.cli-reference 2.0.766 → 2.0.768

package/cli-reference.mdx

@@ -21,8 +21,8 @@ bit COMMAND SUB_COMMAND --help
 ## add
 
 **Alias**: `a`  
-**Description**: track one or more directories as new components  
-Learn the recommended workflow for tracking directories as components, in the link below.
+**Description**: track existing directory contents as new components in the workspace  
+Registers one or more directories as Bit components without changing your files. Each provided path becomes a component root tracked by Bit.
 
 `bit add [path...]`
 
@@ -41,7 +41,10 @@ Learn the recommended workflow for tracking directories as components, in the li
 ## app
 
 **Alias**: `apps`  
-**Description**: Manages apps
+**Description**: manage application components  
+applications are components that create deployable, runnable applications like React apps or Node.js servers.  
+list available apps in the workspace and inspect their configurations.  
+use "bit run" to start an application locally.
 
 `bit app [sub-command]`
 
@@ -59,7 +62,10 @@ Learn the recommended workflow for tracking directories as components, in the li
 
 **Usage**: `app run [app-name]`
 
-**Description**: locally run an app component (independent of bit's dev server)
+**Description**: start an application component locally  
+runs application components in their own development server, separate from the "bit start" UI.  
+apps are components that create deployable applications (React apps, Node.js servers, etc.).  
+when no app name is specified, automatically detects and runs the app if only one exists in the workspace.
 
 | **Arg**    |                                           **Description**                                            |
 | ---------- | :--------------------------------------------------------------------------------------------------: |
@@ -78,10 +84,10 @@ Learn the recommended workflow for tracking directories as components, in the li
 
 ## artifacts
 
-**Description**: list and download component artifacts  
-artifacts are created on isolated capsules during tag or snap commands.  
-example of artifacts are dists files generated by a compiler, a JUnit.xml file generated by a tester  
-and a package.tgz file generated by pkg aspect.
+**Description**: view and download build artifacts  
+displays artifacts created during the build pipeline in isolated capsules during tag or snap operations.  
+artifacts include compiled files, test reports, package files, and other build outputs generated by various tasks.  
+use --out-dir to download artifacts locally for inspection or deployment purposes.
 
 `bit artifacts <component-pattern>`
 
@@ -100,7 +106,10 @@ and a package.tgz file generated by pkg aspect.
 
 ## aspect
 
-**Description**: manage aspects
+**Description**: manage component aspects and their configurations  
+aspects provide functionality and tools for components throughout their development lifecycle.  
+primarily useful for inspecting aspect assignments and configurations with "bit aspect get".  
+rarely used for manual aspect management as most aspects are configured automatically.
 
 `bit aspect <sub-command>`
 
@@ -189,7 +198,10 @@ and a package.tgz file generated by pkg aspect.
 
 ## blame
 
-**Description**: EXPERIMENTAL. per line, show who and when was the last to modify it
+**Description**: EXPERIMENTAL. show line-by-line authorship and modification history  
+displays who last modified each line of a file and when the change was made.  
+tracks line-level changes across component versions.  
+shows author, date, version hash, and optionally commit messages for each line.
 
 `bit blame <filepath>`
 
@@ -205,11 +217,11 @@ and a package.tgz file generated by pkg aspect.
 
 ## build
 
-**Description**: run set of tasks for build.  
-by default, only new and modified components are built.  
-the build takes place in an isolated directories on the filesystem (called "capsules"). the component files are copied to these directories  
-and the package-manager installs the dependencies in the capsules root. once done, the build pipeline is running.  
-because this process can take a while on a large workspace, some flags are available to shorten the process. See the example section for more info.
+**Description**: run build pipeline tasks in isolated environments  
+executes the complete build pipeline including compilation, testing, linting, and other tasks defined by component environments.  
+the build takes place in isolated directories called "capsules" where component files are copied and dependencies are installed via the package manager.  
+by default processes only new and modified components - use --unmodified to build all components.  
+because this process can take a while on large workspaces, various flags are available to optimize the process - see examples for debugging workflows.
 
 `bit build [component-pattern]`
 
@@ -240,11 +252,10 @@ because this process can take a while on a large workspace, some flags are avail
 
 ## capsule
 
-**Description**: manage capsules  
-a capsule is a directory containing the component code, isolated from the workspace.  
-normally, capsules are created during the build process, the component files are copied and the packages are installed  
-via the configured package-manager. the purpose is to compile/test them in isolation to make sure they will work for  
-other users after publishing/exporting them.
+**Description**: manage isolated component environments  
+capsules are temporary isolated directories containing component code and dependencies.  
+automatically created during build processes to compile and test components in isolation.  
+ensures components work independently before publishing, similar to how they'll be consumed.
 
 `bit capsule`
 
@@ -296,7 +307,10 @@ with no args, only workspace's capsules are deleted
 
 ## check-types
 
-**Description**: check typescript types
+**Description**: validate TypeScript type correctness  
+checks for TypeScript type errors in component files, similar to running tsc.  
+by default only checks new and modified components. use --all to check all components.  
+useful for catching type issues before tagging, snapping or building components.
 
 `bit check-types [component-pattern]`
 
@@ -315,14 +329,16 @@ with no args, only workspace's capsules are deleted
 ## checkout
 
 **Alias**: `U`  
-**Description**: switch between component versions or remove local changes
+**Description**: switch between component versions or remove local changes  
+checkout components to specified versions or remove local changes. most commonly used as 'bit checkout head' to get latest versions.  
+the `<to>` argument accepts these values:
 
-`bit checkout <version> [component-pattern]` => checkout the specified ids (or all components when --all is used) to the specified version  
-`bit checkout head [component-pattern]` => checkout to the last snap/tag (use --latest if you only want semver tags), omit [component-pattern] to checkout head for all  
-`bit checkout head~x [component-pattern]` => go backward x generations from the head and checkout to that version  
-`bit checkout latest [component-pattern]` => checkout to the latest satisfying semver tag, omit [component-pattern] to checkout latest for all  
-`bit checkout reset [component-pattern]` => remove local modifications from the specified ids (or all components when --all is used). also, if a component dir is deleted from the filesystem, it'll be restored  
-when on a lane, "checkout head" only checks out components on this lane. to update main components, run "bit lane merge main"
+- head: checkout to last snap/tag (most common usage)
+- specific version: checkout to exact version (e.g. 'bit checkout 1.0.5 component-name')
+- head~x: go back x generations from head (e.g. 'head~2' for two versions back)
+- latest: checkout to latest semver tag
+- reset: remove local modifications and restore original files (also restores deleted component directories)  
+  when on lanes, 'checkout head' only affects lane components. to update main components, run 'bit lane merge main'.
 
 `bit checkout <to> [component-pattern]`
 
@@ -347,7 +363,8 @@ when on a lane, "checkout head" only checks out components on this lane. to upda
 
 ## ci
 
-**Description**: CI commands
+**Description**: continuous integration commands for automated workflows  
+provides commands designed for use in CI/CD pipelines with Git workflows to automate component development tasks like verification, pull request handling, and deployment preparation.
 
 `bit ci <sub-command>`
 
@@ -402,12 +419,15 @@ By default, bumps patch versions when merging to main. If specific configuration
 ## clear-cache
 
 **Alias**: `cc`  
-**Description**: clears Bit's cache from current working machine  
-The following gets removed by this command:
+**Description**: remove cached data to resolve stale data issues  
+clears various caches that Bit uses to improve performance. useful when experiencing stale data issues or  
+unexpected behavior. this command removes:
 
 1. components cache on the filesystem (mainly the dependencies graph and docs)
 2. scope's index file, which maps the component-id:object-hash
 
+note: this cache has minimal impact on disk space. to free significant disk space, use "bit capsule delete --all" to remove build capsules.
+
 `bit clear-cache`
 
 | **Option**               | **Option alias** | **Description**                        |
@@ -416,29 +436,12 @@ The following gets removed by this command:
 
 ---
 
-## cli
-
-**Description**: EXPERIMENTAL. enters bit cli program and generates commands list
-
-`bit cli`
-
-### cli generate
-
-**Usage**: `cli generate`
-
-**Description**: generate an .md file with all commands details
-
-| **Option**   | **Option alias** | **Description**                                                                                                                |
-| ------------ | :--------------: | ------------------------------------------------------------------------------------------------------------------------------ |
-| `--metadata` |                  | metadata/front-matter to place at the top of the .md file, enter as an object e.g. --metadata.id=cli --metadata.title=commands |
-| `--docs`     |                  | generate the cli-reference.docs.mdx file                                                                                       |
-| `--json`     |       `-j`       | output the commands info as JSON                                                                                               |
-
----
-
 ## compile
 
-**Description**: compile components in the workspace
+**Description**: transpile component source files  
+compiles TypeScript, JSX, and other source files into JavaScript using the compiler configured by each component's environment.  
+outputs compiled files to node_modules/component-package-name/dist for consumption by other components.  
+automatically triggered by "bit watch", "bit start", or IDE extensions, but can be run manually for debugging.
 
 `bit compile [component-names...]`
 
@@ -458,7 +461,10 @@ The following gets removed by this command:
 
 ## config
 
-**Description**: config management  
+**Description**: manage Bit configuration settings  
+view and modify Bit configuration at different levels: global, workspace, or scope.  
+configurations control various aspects of Bit including user settings, registries, and feature flags.  
+use environment variables prefixed with BIT*CONFIG* for temporary overrides.  
 https://bit.dev/reference/config/bit-config
 
 `bit config`
@@ -508,7 +514,8 @@ for example, "user.token" becomes "BIT_CONFIG_USER_TOKEN"
 
 ## create
 
-**Description**: create a new component (source files and config) using a template.
+**Description**: scaffold new component(s) from a template (sources, config, and env)  
+Generates one or more components from a chosen template with ready-to-use source files, configuration, and environment. Use it to quickly scaffold consistent components across your workspace. Run 'bit templates' to discover available templates.
 
 `bit create <template-name> <component-names...>`
 
@@ -531,10 +538,10 @@ for example, "user.token" becomes "BIT_CONFIG_USER_TOKEN"
 
 ## delete
 
-**Description**: mark components as deleted on the remote  
-to remove components from your local workspace only, use "bit remove" command.  
-this command marks the components as deleted, and after snap/tag and export they will be marked as deleted from the remote scope as well.  
-unless the '--hard' flag is used (not recommended!), in which case, the component will be deleted from the remote scope immediately.
+**Description**: soft-delete components from remote scopes  
+marks components as deleted so they won't be visible on remote scopes after export.  
+components remain recoverable using "bit recover" unless --hard is used (permanent deletion, not recommended).  
+to remove components from your local workspace only, use "bit remove" instead.
 
 `bit delete <component-pattern>`
 
@@ -556,7 +563,10 @@ unless the '--hard' flag is used (not recommended!), in which case, the componen
 
 ## dependents
 
-**Description**: show dependents of the given component
+**Description**: show components that depend on the specified component  
+displays components from both workspace and scope that depend on the specified component.  
+useful for understanding impact before making changes to a component or when planning refactoring.  
+shows both direct and transitive dependents organized by their origin (workspace vs scope).
 
 `bit dependents <component-name>`
 
@@ -573,7 +583,10 @@ unless the '--hard' flag is used (not recommended!), in which case, the componen
 ## deprecate
 
 **Alias**: `d`  
-**Description**: deprecate a component
+**Description**: mark a component as deprecated to discourage its use  
+marks a component as deprecated locally, then after snap/tag and export it becomes deprecated in the remote scope.  
+optionally specify a replacement component or deprecate only specific version ranges.  
+deprecated components remain available but display warnings when installed or imported.
 
 `bit deprecate <component-name>`
 
@@ -591,7 +604,8 @@ unless the '--hard' flag is used (not recommended!), in which case, the componen
 ## deps
 
 **Alias**: `dependencies`  
-**Description**: manage dependencies
+**Description**: manage component dependencies  
+configure and analyze component dependencies with sub-commands for setting, removing, and inspecting dependency relationships.
 
 `bit deps <sub-command>`
 
@@ -710,7 +724,10 @@ see also "bit deps remove"
 
 **Usage**: `deps usage <dependency-name>`
 
-**Description**: find components that use the specified dependency
+**Description**: find components that use the specified dependency  
+searches workspace components to find which ones depend on the specified package or component.  
+useful for understanding dependency usage before removing packages or when refactoring components.  
+supports both exact version matching and package name patterns.
 
 | **Arg**           |                                                               **Description**                                                                |
 | ----------------- | :------------------------------------------------------------------------------------------------------------------------------------------: |
@@ -734,7 +751,10 @@ see also "bit deps remove"
 
 ## diff
 
-**Description**: show the diff between the components' current source files and config, and their latest snapshot or tag
+**Description**: compare component changes between versions or against the current workspace  
+shows a detailed diff of component files, dependencies, and configuration changes.  
+by default, compares workspace changes against the latest version. specify versions to compare historical changes.  
+supports pattern matching to filter components and various output formats for better readability.
 
 `bit diff [component-pattern] [version] [to-version]`
 
@@ -754,7 +774,10 @@ see also "bit deps remove"
 
 ## doctor
 
-**Description**: diagnose a bit workspace
+**Description**: diagnose and troubleshoot workspace issues  
+runs comprehensive health checks on your workspace to detect and report configuration problems,  
+missing dependencies, corrupted data, and other issues that may affect workspace functionality.  
+can generate diagnostic reports and workspace archives for debugging and support purposes.
 
 `bit doctor [diagnosis-name]`
 
@@ -773,8 +796,10 @@ see also "bit deps remove"
 ## eject
 
 **Alias**: `E`  
-**Description**: remove component from the workspace and install it instead as a regular npm package.  
-By default the component files will be removed from the workspace
+**Description**: remove component from workspace and install it as npm package  
+converts workspace components to external npm packages by removing them from .bitmap and installing via package manager.  
+by default removes component files from workspace. use --keep-files to preserve source code while converting to package dependency.  
+useful for components that no longer need active development in current workspace.
 
 `bit eject <component-pattern>`
 
@@ -793,8 +818,11 @@ By default the component files will be removed from the workspace
 
 ## eject-conf
 
-**Description**: eject components configuration (create a `component.json` file)  
-note this can be reversed at any time by snapping/tagging changes and deleting the component.json file  
+**Description**: create component.json configuration files for components  
+generates component.json files containing component-specific configuration that overrides workspace defaults.  
+useful for customizing individual component settings. alternatively, use commands like "bit env set", "bit deps set", or "bit aspect set".  
+can be reversed by deleting the component.json file and snapping/tagging the changes.
+
 you can use a `<pattern>` for multiple component ids, such as `bit eject-conf "org.scope/utils/**"`.  
 use comma to separate patterns and '!' to exclude. e.g. 'ui/\*\*, !ui/button'  
 use '$' prefix to filter by states/attributes, e.g. '$deprecated', '$modified' or '$env:teambit.react/react'.  
@@ -813,7 +841,9 @@ use `bit pattern --help` to understand patterns better and `bit pattern <pattern
 ## envs
 
 **Alias**: `env`  
-**Description**: list all components maintained by the workspace and their corresponding envs
+**Description**: show components and their assigned environments  
+displays a table showing each workspace component and its corresponding environment.  
+environments control how components are built, tested, linted, and deployed.
 
 `bit envs`
 
@@ -893,11 +923,10 @@ use `bit pattern --help` to understand patterns better and `bit pattern <pattern
 ## export
 
 **Alias**: `e`  
-**Description**: export components from the workspace to remote scopes  
-bit export => export all staged snaps/tags of components to their remote scope. if checked out to a lane, export the lane as well  
- `bit export [pattern...]` => export components included by the pattern to their remote scope (we recommend not using a pattern in  
- most scenarios so that all changes are exported simultaneously)  
- you can use a pattern for multiple ids, such as bit export "utils/\*". (wrap the pattern with quotes to avoid collision with shell commands)
+**Description**: upload components to remote scopes  
+uploads staged versions (snaps/tags) to remote scopes, making them available for consumption by other workspaces.  
+without arguments, exports all staged components. when on a lane, exports the lane as well.  
+exporting is the final step after development and versioning to share components with your team.
 
 `bit export [component-patterns...]`
 
@@ -923,7 +952,10 @@ bit export => export all staged snaps/tags of components to their remote scope.
 
 ## fork
 
-**Description**: create a new component forked from an existing one (copies source files and configs)
+**Description**: create a new component by copying from an existing one  
+duplicates an existing component's source files and configuration to create a new independent component.  
+useful for creating variations or starting development from a similar component.  
+automatically handles import/require statement updates and provides refactoring options.
 
 `bit fork <source-component-id> [target-component-name]`
 
@@ -948,7 +980,10 @@ bit export => export all staged snaps/tags of components to their remote scope.
 
 ## format
 
-**Description**: format components in the development workspace
+**Description**: auto-format component source code  
+formats component files using the formatter configured by each component's environment (Prettier, etc.).  
+by default formats all components. use --changed to format only new and modified components.  
+supports check mode to verify formatting without making changes.
 
 `bit format [component-pattern]`
 
@@ -966,7 +1001,10 @@ bit export => export all staged snaps/tags of components to their remote scope.
 
 ## git
 
-**Description**: perform git operations
+**Description**: Git utilities for Bit repositories  
+provides specialized Git utilities for handling Bit-specific files and conflicts.  
+includes tools for setting up merge drivers for bitmap files and resolving conflicts during Git merges.  
+essential for properly handling Bit's internal files when working with Git repositories.
 
 `bit git <sub-command>`
 
@@ -990,7 +1028,9 @@ bit export => export all staged snaps/tags of components to their remote scope.
 
 ## globals
 
-**Description**: list all globals
+**Description**: display global directories and paths used by Bit  
+shows all global directories including cache, logs, and config locations used by Bit across your system.  
+useful for debugging and understanding where Bit stores data.
 
 `bit globals`
 
@@ -1002,7 +1042,10 @@ bit export => export all staged snaps/tags of components to their remote scope.
 
 ## graph
 
-**Description**: generate an SVG image file with the components' dependencies graph
+**Description**: visualize component dependencies as a graph image  
+generates an SVG (or PNG) image showing component dependency relationships.  
+black arrows represent runtime dependencies, red arrows show dev or peer dependencies.  
+by default shows only workspace components; use --include-dependencies for full dependency tree.
 
 `bit graph [id]`
 
@@ -1021,7 +1064,8 @@ bit export => export all staged snaps/tags of components to their remote scope.
 ## help
 
 **Alias**: `$0`  
-**Description**: shows help
+**Description**: display available commands and usage information  
+shows a categorized list of all available Bit commands with brief descriptions. use `bit <command> --help` for detailed help on specific commands.
 
 `bit help`
 
@@ -1033,7 +1077,10 @@ bit export => export all staged snaps/tags of components to their remote scope.
 
 ## import
 
-**Description**: import components from their remote scopes to the local workspace
+**Description**: bring components from remote scopes into your workspace  
+brings component source files from remote scopes into your workspace and installs their dependencies as packages.  
+supports pattern matching for bulk imports, merge strategies for handling conflicts, and various optimization options.  
+without arguments, fetches all workspace components' latest versions from their remote scopes.
 
 `bit import [component-patterns...]`
 
@@ -1071,8 +1118,10 @@ bit export => export all staged snaps/tags of components to their remote scope.
 
 ## init
 
-**Description**: create or reinitialize an empty workspace  
-if the current directory is already a workspace, it validates that bit files are correct and rewrite them if needed.
+**Description**: initialize a Bit workspace in an existing project  
+creates Bit configuration files in an existing project directory to start tracking components.  
+if already a workspace, validates and repairs Bit files as needed.  
+supports various reset options to recover from corrupted state or restart from scratch.
 
 `bit init [path]`
 
@@ -1100,8 +1149,10 @@ if the current directory is already a workspace, it validates that bit files are
 ## install
 
 **Alias**: `in`  
-**Description**: installs workspace dependencies  
-when no package is specified, all workspace dependencies are installed and all workspace components are imported.
+**Description**: install workspace dependencies  
+installs workspace dependencies and prepares the workspace for development.  
+when packages are specified, adds them to workspace.jsonc policy and installs. when no packages specified, installs existing dependencies.  
+automatically imports components, compiles components, links to node_modules, and writes config files.
 
 `bit install [packages...]`
 
@@ -1131,7 +1182,10 @@ when no package is specified, all workspace dependencies are installed and all w
 ## lane
 
 **Alias**: `l`  
-**Description**: manage lanes - if no sub-command is used, runs "bit lane list"
+**Description**: manage lanes for parallel development  
+lanes allow isolated development of features without affecting main branch components.  
+create, switch between, and merge lanes to coordinate parallel work across teams.  
+without a sub-command, lists all available lanes.
 
 `bit lane [sub-command]`
 
@@ -1483,7 +1537,10 @@ this command does the following:
 
 ## link
 
-**Description**: create links in the node_modules directory, to core aspects and to components in the workspace
+**Description**: create links between components and node_modules  
+creates links in node_modules for workspace components and core aspects, enabling import resolution.  
+automatically links all workspace components and Bit's core aspects to their respective package names.  
+useful for development when components need to reference each other or when debugging linking issues.
 
 `bit link [component-names...]`
 
@@ -1505,7 +1562,10 @@ this command does the following:
 
 ## lint
 
-**Description**: lint components in the development workspace
+**Description**: analyze component code for issues and style violations  
+runs linters configured by each component's environment (ESLint, etc.) to check for code quality issues.  
+by default lints all components. use --changed to lint only new and modified components.  
+supports automatic fixing of certain issues with --fix flag.
 
 `bit lint [component-pattern]`
 
@@ -1525,7 +1585,10 @@ this command does the following:
 ## list
 
 **Alias**: `ls`  
-**Description**: list components on a workspace or a remote scope (with flag).
+**Description**: display components in workspace or remote scope  
+shows components in the current workspace by default, or from a specified remote scope.  
+supports filtering by scope, namespace, and various display options.  
+use --outdated to highlight components that have newer versions available.
 
 `bit list [remote-scope]`
 
@@ -1543,7 +1606,10 @@ this command does the following:
 
 ## local-only
 
-**Description**: manage local-only components, which reside only in the workspace and are not snapped/tagged
+**Description**: manage components that exist only in the workspace  
+controls components that are excluded from versioning (snap/tag) and exporting operations.  
+local-only components are useful for workspace-specific tools, configs, or temporary components.  
+these components remain in the workspace but won't be shared or versioned.
 
 `bit local-only <sub-command>`
 
@@ -1577,7 +1643,10 @@ this command does the following:
 
 ## log
 
-**Description**: show components(s) version history
+**Description**: display component version history  
+shows chronological history of component versions including tags and snaps with metadata.  
+displays commit messages, authors, dates, and version information. supports both local and remote component logs.  
+use various format options for compact or detailed views of version history.
 
 `bit log <id>`
 
@@ -1599,7 +1668,10 @@ this command does the following:
 
 ## log-file
 
-**Description**: EXPERIMENTAL. show file history
+**Description**: EXPERIMENTAL. display history of changes to a specific file  
+shows version history for a specific file within component versions.  
+tracks file-level changes across component snaps and tags.  
+displays file modifications, hashes, and associated commit information.
 
 `bit log-file <filepath>`
 
@@ -1615,7 +1687,10 @@ this command does the following:
 
 ## login
 
-**Description**: log in to Bit cloud
+**Description**: authenticate with Bit Cloud for component publishing and collaboration  
+opens browser to authenticate with Bit Cloud (bit.cloud) and obtain access token for publishing components.  
+automatically updates .npmrc file with registry configuration and authentication token for seamless package publishing.  
+supports custom cloud domains, CI/machine authentication, and manual token refresh options.
 
 `bit login`
 
@@ -1634,7 +1709,10 @@ this command does the following:
 
 ## logout
 
-**Description**: log the CLI out of Bit
+**Description**: sign out of Bit Cloud and clear authentication tokens  
+removes stored authentication tokens and signs out of Bit Cloud.  
+clears local credentials while preserving .npmrc configurations.  
+use this to switch between accounts or when authentication tokens expire.
 
 `bit logout`
 
@@ -1642,7 +1720,10 @@ this command does the following:
 
 ## mcp-server
 
-**Description**: Start the Bit CLI Model Context Protocol (MCP) server for programmatic and remote access to Bit commands.
+**Description**: start Model Context Protocol server for AI assistants  
+enables AI assistants and other tools to interact with Bit via the Model Context Protocol.  
+provides a standardized interface for AI agents to execute Bit commands and access component information.  
+allows writing custom instructions and rules to guide AI agents in their interactions with Bit.
 
 `bit mcp-server [sub-command]`
 
@@ -1704,11 +1785,12 @@ Creates or updates rules/instructions markdown files to provide AI assistants wi
 
 ## merge
 
-**Description**: merge changes of the remote head into local - auto-snaps all merged components  
-merge changes of the remote head into local when they are diverged. when on a lane, merge the remote head of the lane into the local  
-and creates snaps for merged components that have diverged, on the lane.  
-if no ids are specified, all pending-merge components will be merged. (run "bit status" to list them).  
-optionally use '--abort' to revert the last merge. to revert a lane merge, use "bit lane merge-abort" command.
+**Description**: merge diverged component history when local and remote have different versions  
+resolves diverged component history when both local and remote have created different snaps/tags from the same base version.  
+if no component pattern is specified, all pending-merge components will be merged (run 'bit status' to list them).  
+'bit status' will show diverged components and suggest either merging or resetting local changes.  
+preferred approach: use 'bit reset' to remove local versions, then 'bit checkout head' to get remote versions.  
+for lane-to-lane merging, use 'bit lane merge' instead.
 
 `bit merge [component-pattern]`
 
@@ -1735,8 +1817,10 @@ optionally use '--abort' to revert the last merge. to revert a lane merge, use "
 ## move
 
 **Alias**: `mv`  
-**Description**: move a component to a different filesystem path  
-(note: this does NOT affect the component's name or scope, just its location in the workspace)
+**Description**: relocate a component to a different directory  
+moves component files to a new location within the workspace and updates the .bitmap tracking.  
+only changes the filesystem location - does not affect the component's name, scope, or ID.  
+useful for reorganizing workspace structure or following new directory conventions.
 
 `bit move <current-component-dir> <new-component-dir>`
 
@@ -1749,7 +1833,10 @@ optionally use '--abort' to revert the last merge. to revert a lane merge, use "
 
 ## new
 
-**Description**: create a new workspace from a template
+**Description**: create a new Bit workspace from a template  
+initializes a new Bit workspace with pre-configured settings, environments, and optionally starter components.  
+templates provide different setups for React, Angular, Node.js, or custom development workflows.  
+installs dependencies and configures the workspace for immediate development.
 
 `bit new <template-name> <workspace-name>`
 
@@ -1774,7 +1861,10 @@ optionally use '--abort' to revert the last merge. to revert a lane merge, use "
 
 ## npmrc
 
-**Description**: manage npmrc file with scope, registry, and token information from bit.cloud
+**Description**: configure .npmrc file with Bit Cloud registry and authentication settings  
+manages .npmrc configuration for seamless package installation from Bit Cloud registries.  
+automatically configures scoped registries and authentication tokens for your workspace components.  
+provides sub-commands for generating, updating, and managing npm registry configurations.
 
 `bit npmrc [sub-command]`
 
@@ -1793,7 +1883,7 @@ optionally use '--abort' to revert the last merge. to revert a lane merge, use "
 
 ## pattern
 
-**Description**: list the component ids matching the given pattern  
+**Description**: test and validate component patterns  
 this command helps validating a pattern before using it in other commands.  
 NOTE: always wrap the pattern with quotes to avoid collision with shell commands. depending on your shell, it might be single or double quotes.  
 a pattern can be a simple component-id or component-name. e.g. 'ui/button'.  
@@ -1818,7 +1908,8 @@ to match a state and another criteria, use " AND " keyword. e.g. '$modified AND
 
 ## recover
 
-**Description**: recover component(s) soft-deleted from the workspace, or a remote scope
+**Description**: restore soft-deleted components  
+reverses the soft-deletion of components marked with "bit delete", restoring them to their previous state. works for both local and remote soft-deleted components.
 
 `bit recover <component-name>`
 
@@ -1831,7 +1922,10 @@ to match a state and another criteria, use " AND " keyword. e.g. '$modified AND
 
 ## refactor
 
-**Description**: source code refactoring / codemod
+**Description**: automatically refactor component source code  
+performs automated code transformations and refactoring operations across components.  
+currently supports updating import/require statements when component names or dependencies change.  
+useful for maintaining code consistency after renaming or restructuring components.
 
 `bit refactor <sub-command>`
 
@@ -1846,7 +1940,10 @@ the `<old-id>` and `<new-id>` arguments can be either a component-id or a packag
 
 ## remote
 
-**Description**: manage set of tracked bit scope(s)
+**Description**: manage remote scopes for self-hosted environments  
+configure connections to self-hosted remote scopes via HTTP or file protocol.  
+note: this command is only needed for self-hosted scopes. when using bit.cloud, remote scopes are automatically configured.  
+remotes are bare scopes that store exported components and enable collaboration across teams.
 
 `bit remote`
 
@@ -1891,8 +1988,10 @@ for example: "http://localhost:3000", "file:///tmp/local-scope"
 ## remove
 
 **Alias**: `rm`  
-**Description**: remove component(s) from the local workspace  
-to mark components as deleted on the remote scope, use "bit delete".
+**Description**: untrack components from the workspace  
+removes components from the local workspace only - stops tracking them in .bitmap and deletes their files by default.  
+does not affect remote scopes - to delete components from remotes, use "bit delete" instead.  
+use --keep-files to preserve component files while only removing the tracking.
 
 `bit remove <component-pattern>`
 
@@ -1911,7 +2010,10 @@ to mark components as deleted on the remote scope, use "bit delete".
 
 ## rename
 
-**Description**: rename component. if exported, create a new component and delete the original component. otherwise just renames current component
+**Description**: change a component name  
+renames a component and optionally refactors dependent code to use the new name.  
+for exported components: creates a new component with the new name and marks the original as deleted.  
+for local components: simply renames the existing component in place.
 
 `bit rename <current-name> <new-name>`
 
@@ -1934,8 +2036,10 @@ to mark components as deleted on the remote scope, use "bit delete".
 
 ## reset
 
-**Description**: revert tagged or snapped versions for component(s)  
-https://bit.dev/components/tags#undoing-a-tag
+**Description**: revert local tags and snaps to previous versions  
+removes local component versions (tags/snaps) that haven't been exported yet.  
+by default reverts all local versions. use --head to revert only the latest version.  
+useful for undoing mistakes before exporting. exported versions cannot be reset.
 
 `bit reset [component-pattern]`
 
@@ -1955,7 +2059,9 @@ https://bit.dev/components/tags#undoing-a-tag
 
 ## revert
 
-**Description**: replace the current component files by the specified version, leave the version intact
+**Description**: replace component files with specified version while preserving current version  
+replaces component source files with files from the specified version but keeps the current component version.  
+useful for reverting file changes without changing the component's version history. different from checkout which changes the version.
 
 `bit revert <component-pattern> <to>`
 
@@ -1974,7 +2080,10 @@ https://bit.dev/components/tags#undoing-a-tag
 ## run
 
 **Alias**: `c`  
-**Description**: locally run an app component (independent of bit's dev server)
+**Description**: start an application component locally  
+runs application components in their own development server, separate from the "bit start" UI.  
+apps are components that create deployable applications (React apps, Node.js servers, etc.).  
+when no app name is specified, automatically detects and runs the app if only one exists in the workspace.
 
 `bit run [app-name]`
 
@@ -1995,9 +2104,10 @@ https://bit.dev/components/tags#undoing-a-tag
 
 ## schema
 
-**Description**: extracts and displays the API schema (types, functions, classes, interfaces) of the specified component/s.  
-Extracts TypeScript definitions to provide a comprehensive view of a component's public API.  
-Shows detailed information about exported elements including classes, interfaces, functions, types, and enums with their respective signatures and documentation.
+**Description**: display component API schema and type definitions  
+extracts and displays the public API structure of components including types, functions, classes, and interfaces.  
+shows detailed type information, function signatures, and JSDoc documentation for exported elements.  
+useful for understanding component interfaces and generating documentation.
 
 you can use a `<pattern>` for multiple component ids, such as `bit schema "org.scope/utils/**"`.  
 use comma to separate patterns and '!' to exclude. e.g. 'ui/\*\*, !ui/button'  
@@ -2016,7 +2126,10 @@ use `bit pattern --help` to understand patterns better and `bit pattern <pattern
 
 ## scope
 
-**Description**: manage the scope-name for components
+**Description**: manage component scope names and assignments  
+configure scope assignments for components including setting default scopes and renaming existing scopes.  
+scopes determine where components are stored and published, forming the first part of component IDs.  
+essential for organizing components and managing component namespaces across teams.
 
 `bit scope <sub-command>`
 
@@ -2097,20 +2210,25 @@ optionally, provide [pattern] to limit the fork to specific components
 
 ## set-peer
 
-**Description**: set a component as always peer
+**Description**: configure component to always be installed as peer dependency  
+marks a component to always be treated as a peer dependency when used by other components.  
+useful for shared libraries that should be provided by the consuming application.  
+the specified version range will be used when adding this component as a peer dependency.
 
 `bit set-peer <component-id> <range>`
 
-| **Arg**        |                               **Description**                               |
-| -------------- | :-------------------------------------------------------------------------: |
-| `component-id` |                     the component to set as always peer                     |
-| `range`        | the default range to use for the componnent, when added to peerDependencies |
+| **Arg**        |                              **Description**                               |
+| -------------- | :------------------------------------------------------------------------: |
+| `component-id` |                    the component to set as always peer                     |
+| `range`        | the default range to use for the component, when added to peerDependencies |
 
 ---
 
 ## show
 
-**Description**: display the component's essential information
+**Description**: display component metadata, dependencies, and configuration  
+shows detailed information about a component including its version, dependencies, environment, and other metadata.  
+note: to see file changes made in a specific version, use `bit diff <component> <version> --parent`.
 
 `bit show <component-name>`
 
@@ -2130,7 +2248,10 @@ optionally, provide [pattern] to limit the fork to specific components
 
 ## snap
 
-**Description**: create an immutable and exportable component snapshot (non-release version)
+**Description**: create immutable component snapshots for development versions  
+creates snapshots with hash-based versions for development and testing. snapshots are immutable and exportable.  
+by default snaps only new and modified components. use for development iterations before creating semantic version tags.  
+snapshots maintain component history and enable collaboration without formal releases.
 
 `bit snap [component-pattern]`
 
@@ -2161,7 +2282,10 @@ optionally, provide [pattern] to limit the fork to specific components
 ## start
 
 **Alias**: `c`  
-**Description**: run the ui/development server
+**Description**: launch the Bit development server  
+starts the local development server providing a UI to browse, preview, and interact with components.  
+works in both workspaces and scopes. opens automatically in your browser at http://localhost:3000 (or specified port).  
+includes hot module reloading for development.
 
 `bit start [component-pattern]`
 
@@ -2185,7 +2309,9 @@ optionally, provide [pattern] to limit the fork to specific components
 
 ## stash
 
-**Description**: stash modified components
+**Description**: temporarily save and restore component changes  
+temporarily stores modified component files without creating versions.  
+allows saving work-in-progress changes and switching context, then restoring changes later.
 
 `bit stash <sub-command>`
 
@@ -2230,7 +2356,10 @@ optionally, provide [pattern] to limit the fork to specific components
 ## status
 
 **Alias**: `s`  
-**Description**: present the current status of components in the workspace, including indication of detected issues
+**Description**: show workspace component status and issues  
+displays the current state of all workspace components including new, modified, staged, and problematic components.  
+identifies blocking issues that prevent tagging/snapping and provides warnings with --warnings flag.  
+essential for understanding workspace health before versioning components.
 
 `bit status`
 
@@ -2248,7 +2377,9 @@ optionally, provide [pattern] to limit the fork to specific components
 
 ## system
 
-**Description**: system operations
+**Description**: access system-level operations and debugging tools  
+provides commands for system-level operations including viewing and tailing debug logs.  
+useful for troubleshooting issues and monitoring Bit's internal operations in real-time.
 
 `bit system <sub-command>`
 
@@ -2270,9 +2401,10 @@ similar to linux "tail -f" command
 ## tag
 
 **Alias**: `t`  
-**Description**: create an immutable and exportable component snapshot, tagged with a release version.  
-if no patterns are provided, it will tag all new and modified components.  
-if patterns are entered, you can specify a version per pattern using "@" sign, e.g. bit tag foo@1.0.0 bar@minor baz@major
+**Description**: create immutable component snapshots with semantic version tags  
+creates tagged versions using semantic versioning (semver) for component releases. tags are immutable and exportable.  
+by default tags all new and modified components. supports version specification per pattern using "@" (e.g. foo@1.0.0, bar@minor).  
+use for official releases. for development versions, use 'bit snap' instead.
 
 `bit tag [component-patterns...]`
 
@@ -2315,8 +2447,8 @@ if patterns are entered, you can specify a version per pattern using "@" sign, e
 
 ## templates
 
-**Description**: list available templates for "bit create" and "bit new"  
-list components templates when inside bit-workspace (for bit-create), otherwise, list workspace templates (for bit-new)
+**Description**: list available templates for creating components and workspaces  
+Lists available templates. Inside a workspace it shows component templates for 'bit create'; outside a workspace it shows workspace templates for 'bit new'.
 
 `bit templates`
 
@@ -2331,7 +2463,10 @@ list components templates when inside bit-workspace (for bit-create), otherwise,
 ## test
 
 **Alias**: `at`  
-**Description**: test components in the workspace. by default only runs tests for new and modified components
+**Description**: run component tests  
+executes tests using the testing framework configured by each component's environment (Jest, Mocha, etc.).  
+by default only runs tests for new and modified components. use --unmodified to test all components.  
+supports watch mode, coverage reporting, and debug mode for development workflows.
 
 `bit test [component-pattern]`
 
@@ -2356,7 +2491,8 @@ list components templates when inside bit-workspace (for bit-create), otherwise,
 
 ## undeprecate
 
-**Description**: undeprecate a deprecated component (local/remote)
+**Description**: remove the deprecation status from a component  
+reverses the deprecation of a component, removing warnings and allowing normal use again.
 
 `bit undeprecate <id>`
 
@@ -2365,15 +2501,22 @@ list components templates when inside bit-workspace (for bit-create), otherwise,
 ## uninstall
 
 **Alias**: `un`  
-**Description**: uninstall dependencies
+**Description**: remove dependencies from workspace  
+removes specified packages from workspace.jsonc dependency policy and runs install to update node_modules.
 
 `bit uninstall [packages...]`
 
+| **Arg**       |                       **Description**                       |
+| ------------- | :---------------------------------------------------------: |
+| `packages...` | list of package names to remove from workspace dependencies |
+
 ---
 
 ## unset-peer
 
-**Description**: unset a component as always peer
+**Description**: remove always-peer configuration from component  
+removes the always-peer marking from a component, allowing it to be installed as a regular dependency.  
+reverses the effect of 'bit set-peer' command. the component will be treated normally in dependency resolution.
 
 `bit unset-peer <component-id>`
 
@@ -2386,7 +2529,10 @@ list components templates when inside bit-workspace (for bit-create), otherwise,
 ## update
 
 **Alias**: `up`  
-**Description**: update dependencies. By default, dependencies are updated to the highest semver compatible versions.
+**Description**: update workspace dependencies to newer versions  
+updates dependencies in workspace.jsonc to newer versions and runs install to apply changes.  
+by default, updates to highest semver-compatible versions. use --major, --minor, or --patch for specific version types.  
+supports glob patterns to update specific packages. prompts for confirmation unless --yes is specified.
 
 `bit update [package-patterns...]`
 
@@ -2406,7 +2552,7 @@ list components templates when inside bit-workspace (for bit-create), otherwise,
 
 ## version
 
-**Description**: shows bit version
+**Description**: display the installed Bit version
 
 `bit version`
 
@@ -2416,62 +2562,12 @@ list components templates when inside bit-workspace (for bit-create), otherwise,
 
 ---
 
-## version-history
-
-**Alias**: `vh`  
-**Description**: manage the version-history of components
-
-`bit version-history <sub-command>`
-
-### version-history graph
-
-**Usage**: `version-history graph <component-id>`
-
-**Description**: generate a graph of the version history of a component and save as an SVG file
-
-| **Option**         | **Option alias** | **Description**                                                                                        |
-| ------------------ | :--------------: | ------------------------------------------------------------------------------------------------------ |
-| `--short-hash`     |       `-s`       | show only 9 chars of the hash                                                                          |
-| `--mark <string>`  |       `-m`       | paint the given node-ids in the graph in red color, for multiple, separate by commas                   |
-| `--png`            |                  | save the graph as a png file instead of svg. requires "graphviz" to be installed                       |
-| `--layout <name>`  |       `-l`       | GraphVis layout. default to "dot". options are [circo, dot, fdp, neato, osage, patchwork, sfdp, twopi] |
-| `--limit <number>` |                  | limit the number of nodes in the graph (starting from the heads)                                       |
-
-### version-history show
-
-**Usage**: `version-history show <component-id>`
-
-**Description**: show the version-history of a component
-
-| **Option**     | **Option alias** | **Description**               |
-| -------------- | :--------------: | ----------------------------- |
-| `--short-hash` |       `-s`       | show only 9 chars of the hash |
-| `--json`       |       `-j`       | json format                   |
-
-### version-history build
-
-**Usage**: `version-history build <component-pattern>`
-
-**Description**: rebuild the version history of a component. helpful when it got corrupted for some reason
-
-| **Arg**             |                                                                                                                                                                                                                 **Description**                                                                                                                                                                                                                 |
-| ------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
-| `component-pattern` | component name, component id, or component pattern. use component pattern to select multiple components. wrap the pattern with quotes. use comma to separate patterns and "!" to exclude. e.g. "ui/\*\*, !ui/button". use '$' prefix to filter by states/attributes, e.g. '$deprecated', '$modified' or '$env:teambit.react/react'. use `bit pattern --help` to understand patterns better and `bit pattern <pattern>` to validate the pattern. |
-
-| **Option**           | **Option alias** | **Description**                                                                           |
-| -------------------- | :--------------: | ----------------------------------------------------------------------------------------- |
-| `--from-snap <snap>` |                  | build the version history from a specific snap. the pattern must be a single component-id |
-| `--from-all-lanes`   |                  | build the version history from the heads of all lanes that include this component         |
-| `--delete-existing`  |                  | delete the existing version history before building it                                    |
-| `--remote <scope>`   |                  | make the change on the remote scope                                                       |
-
----
-
 ## watch
 
-**Description**: automatically recompile modified components (on save)  
-by default, the watcher doesn't use polling, to keep the CPU idle.  
-if this doesn't work well for you, run "bit config set watch_use_polling true" to use polling.
+**Description**: watch and compile components on file changes  
+monitors component files for changes and automatically recompiles them using their environment's configured compiler.  
+enables immediate feedback during development by keeping components compiled as you work.  
+by default uses file system events (not polling) to minimize CPU usage - enable polling with "bit config set watch_use_polling true" if needed.
 
 `bit watch`
 
@@ -2489,7 +2585,10 @@ if this doesn't work well for you, run "bit config set watch_use_polling true" t
 
 ## whoami
 
-**Description**: display the currently logged in user
+**Description**: display the currently authenticated Bit Cloud user  
+shows the username of the currently logged in Bit Cloud account.  
+verifies authentication status with the cloud service and displays the active username.  
+useful for confirming authentication before publishing or when switching between accounts.
 
 `bit whoami`
 
@@ -2497,7 +2596,10 @@ if this doesn't work well for you, run "bit config set watch_use_polling true" t
 
 ## why
 
-**Description**: find components that use the specified dependency
+**Description**: find components that use the specified dependency  
+searches workspace components to find which ones depend on the specified package or component.  
+useful for understanding dependency usage before removing packages or when refactoring components.  
+supports both exact version matching and package name patterns.
 
 `bit why <dependency-name>`
 
@@ -2514,7 +2616,10 @@ if this doesn't work well for you, run "bit config set watch_use_polling true" t
 ## ws-config
 
 **Alias**: `workspace-config`  
-**Description**: manage workspace config files
+**Description**: generate IDE configuration files  
+writes configuration files (tsconfig.json, eslintrc.js, etc.) to your workspace for better IDE support.  
+automatically generates configs based on your components' environments and settings.  
+useful for enabling proper IntelliSense, linting, and type-checking in your IDE.
 
 `bit ws-config <sub-command>`