# Bahmcloud Store - Full User Guide This guide explains the current feature set of Bahmcloud Store (BCS) for Home Assistant. BCS is a git-based store UI that can currently manage integrations and blueprints from multiple repository providers. --- ## Contents - Concepts - Sources - Supported Content Types - UI Overview - Finding Repositories - Installing - Selecting Versions - Updating - Uninstalling - Pinned Repositories - Release Notes - Backups and Restore - Custom Repositories - HACS Repositories - Update Entities - Performance and Caching - Restart Behavior - Troubleshooting - FAQ --- ## Concepts ### Sources - **BCS Official**: repositories from the official Bahmcloud index - **HACS**: optional HACS integration source - **Custom**: repositories you add manually by URL ### Installed Ref BCS stores the installed ref separately from any version declared inside the repository itself. That makes update checks more reliable when a repository uses tags or releases that do not exactly match its internal manifest version. --- ## Supported Content Types ### Integrations - Source layout: `custom_components//...` - Install target: `/config/custom_components/` - Supports install, update, downgrade, uninstall, backups, restore, and update entities - Restart required after install, update, uninstall, or restore ### Blueprints - Source layout: `blueprints/...` - Install target: `/config/blueprints/...` - Supports install, update, uninstall, backup, and restore through the store - Intended for blueprint repositories without integration-specific folder structures --- ## UI Overview Store view: - Search - Source filter - Category filter - State filter - Sorting - HACS source toggle - Pinned repository filtering and sorting Repository detail view: - README rendering - Release notes for provider releases - Version selector - Install / Update / Uninstall actions - Pin / Unpin action - Backup restore action for integrations - Category and install target information --- ## Finding Repositories 1. Use **Search** to filter by name, description, or URL. 2. Use **Source** to switch between BCS Official, HACS, and Custom repositories. 3. Use **Category** to focus on a specific content type. 4. Use **Pinned** filtering or sorting to surface repositories you watch often. Descriptions, metadata, and latest versions may appear progressively because BCS enriches repository information in the background. --- ## Installing ### Integration Install 1. Open a repository. 2. Optionally select a version. 3. Click **Install**. 4. Restart Home Assistant when prompted. Internally, BCS: - downloads the selected repository archive - extracts `custom_components/...` - installs every valid integration found there - stores the installed ref - creates backups before overwriting existing integration folders ### Blueprint Install 1. Open a blueprint repository. 2. Optionally select a version. 3. Click **Install**. Internally, BCS: - downloads the selected repository archive - extracts `blueprints/...` - copies blueprint files into `/config/blueprints/...` Blueprint installs normally do not require a Home Assistant restart. --- ## Selecting Versions - Use the version selector in the detail view. - `Latest` uses the newest provider release or tag BCS can determine. - You can install an older release or tag when available. - Release notes are shown when the selected version is a provider release with a body. --- ## Updating ### Integrations - The **Update** button appears when the latest ref differs from the installed ref. - Updates are also available through **Settings -> Updates** via native Home Assistant update entities. - Integration updates create backups before overwriting files. ### Blueprints - Blueprint repositories can also be updated or reinstalled from another selected version. - Blueprint updates create content backups before overwriting files. - The current blueprint path handling is focused on direct deployment to the blueprints folder. --- ## Uninstalling ### Integrations - Removes the installed integration directories from `/config/custom_components` - Clears the installed state in BCS - Usually requires a restart ### Blueprints - Removes the installed blueprint files recorded by BCS - Cleans up empty directories below `/config/blueprints` when possible - Does not require a restart under normal conditions --- ## Pinned Repositories You can pin repositories to keep important items easy to find. Current behavior: - Pin or unpin from the detail view - Filter the store by pinned repositories - Sort the store with pinned repositories first - Pinned repositories show a dedicated badge in the store overview - Pinned state is persisted in settings --- ## Release Notes When a provider release has a release body, BCS can show release notes in the detail view for the selected version. Notes: - Release notes are available for real releases, not every tag or branch - If no provider release body exists, BCS shows a clear not-available state --- ## Backups and Restore Integration installs and updates create backups before overwriting existing files. Blueprint updates also create content backups before overwriting deployed blueprint files. Backup path: `/config/.bcs_backups///` Restore flow: 1. Open the repository detail 2. Click **Restore** 3. Select a backup 4. Confirm restore 5. Restart Home Assistant if prompted Restore is available for integrations and blueprints. Blueprint restore flow: 1. Open the blueprint repository detail 2. Click **Restore** 3. Select a backup 4. Confirm restore Blueprint restores overwrite the recorded installed files under `/config/blueprints/...` and normally do not require a restart. --- ## Custom Repositories You can add any public repository URL that matches a supported provider style and contains supported content. BCS attempts to detect: - provider - default branch - latest version - metadata from `bcs.yaml`, `hacs.yaml`, or `hacs.json` - README content Custom repositories get a **Custom** badge and can be filtered separately. --- ## HACS Repositories Enable the HACS toggle to include official HACS integration repositories. Current scope: - HACS source support is currently focused on integrations - HACS metadata is used to improve naming and descriptions --- ## Update Entities BCS exposes Home Assistant update entities for installed integrations. - Found under **Settings -> Updates** - Shows installed ref and latest ref - Lets Home Assistant trigger the BCS update pipeline Blueprint repositories do not currently use the integration-style update entity flow. --- ## Performance and Caching BCS is designed to keep startup responsive. - Heavy work runs after Home Assistant startup - Repo data is enriched in the background - Repository details are cached - Version lists are cached - HACS metadata is cached Opening a repository detail view can force immediate enrichment for that repository. --- ## Restart Behavior Restart usually matters only for integration changes. - Integration install/update/uninstall/restore: restart expected - Blueprint install/update/uninstall/restore: restart usually not needed BCS uses a Home Assistant repair flow to surface restart requirements for integration changes. --- ## Troubleshooting - **Latest version missing**: open the repository detail once to force a recheck - **Release notes missing**: the selected version may be a tag or branch without a provider release body - **Blueprint install fails**: verify the repository really contains a `blueprints/` folder - **Integration install fails**: verify the repository contains `custom_components//manifest.json` - **Repo appears but cannot install**: metadata can describe the category, but the repository layout still has to match that category --- ## FAQ ### Where are integrations installed? `/config/custom_components/` ### Where are blueprints installed? `/config/blueprints/...` ### Are pinned repositories persistent? Yes. ### Do blueprints require a restart? Usually no. ### Do integrations require a restart? Yes, normally after install, update, uninstall, or restore.