8.1 KiB
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/<domain>/... - Install target:
/config/custom_components/<domain> - 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
- Use Search to filter by name, description, or URL.
- Use Source to switch between BCS Official, HACS, and Custom repositories.
- Use Category to focus on a specific content type.
- 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
- Open a repository.
- Optionally select a version.
- Click Install.
- 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
- Open a blueprint repository.
- Optionally select a version.
- 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.
Latestuses 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/blueprintswhen 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/<domain>/<timestamp>/
Restore flow:
- Open the repository detail
- Click Restore
- Select a backup
- Confirm restore
- Restart Home Assistant if prompted
Restore is available for integrations and blueprints.
Blueprint restore flow:
- Open the blueprint repository detail
- Click Restore
- Select a backup
- 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, orhacs.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/<domain>/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/<domain>
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.