Add init command and installer upgrade flow

.github/release-drafter.yml

@@ -24,10 +24,12 @@ categories:
   - title: 🧰 Maintenance
     labels:
       - maintenance
+  - title: 📝 Documentation
+    labels:
+      - documentation
 
 exclude-labels:
   - skip-changelog
-  - documentation
 
 autolabeler:
   - label: documentation

.github/release.yml

@@ -2,7 +2,6 @@ changelog:
   exclude:
     labels:
       - skip-changelog
-      - documentation
   categories:
     - title: 🚀 Features
       labels:
@@ -13,6 +12,9 @@ changelog:
     - title: 🧰 Maintenance
       labels:
         - maintenance
+    - title: 📝 Documentation
+      labels:
+        - documentation
     - title: Other Changes
       labels:
         - "*"

.github/workflows/ci.yaml

@@ -66,3 +66,17 @@ jobs:
         with:
           name: clackhouse-${{ matrix.os }}
           path: target/release/clackhouse
+
+  install-smoke:
+    name: Install Smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    needs: [fmt, clippy, test]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Smoke test install.sh and init
+        run: ./scripts/install-smoke-test.sh

CHANGELOG.md

@@ -7,5 +7,7 @@ All notable changes to this project will be documented in this file.
 - bootstrap the first `clackhouse` CLI in Rust
 - add `clackhouse version`
 - add a `curl ... | sh` installer path backed by release archives
+- add daily CLI update notices that point users back to the installer flow
+- verify release checksums during install and support stable or RC reinstall channels
 - align CLI release automation and asset format with the `agent` repository
 - add maintainer scaffolding aligned with the `agent` repository

README.md

@@ -1,9 +1,9 @@
 # ClackHouse CLI
 
-The first PR is intentionally tiny:
+Current commands:
 
+- `clackhouse init`
 - `clackhouse version`
-- `curl ... | sh` install and uninstall paths for the CLI binary
 
 ## Install
 
@@ -20,6 +20,24 @@ Or install from a release archive with:
 curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh
 ```
 
+Install the latest release candidate instead with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh -s -- --channel rc
+```
+
+Then install the default pinned `clackhouse-agent` target with:
+
+```bash
+clackhouse init
+```
+
+By default the CLI points to the pinned agent release `2026.4.2`. You can see that target in `clackhouse version`, or override it at install time:
+
+```bash
+clackhouse init --agent-version 2026.4.2
+```
+
 Remove the installed binary with:
 
 ```bash
@@ -28,6 +46,8 @@ curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/uninstall.sh |
 
 `uninstall.sh` removes only the `clackhouse` binary from known install locations. It does not remove any future config, data, or agent state.
 
+ClackHouse runtime config and state stay under `~/.clackhouse`. That already matches the current agent defaults, so no config-location change is needed for `init`.
+
 That installer expects release assets named like:
 
 - `clackhouse-aarch64-apple-darwin.zip`
@@ -40,12 +60,30 @@ This now matches the `agent` release format:
 - macOS archives are `.zip`
 - Linux archives are `.tar.gz`
 - releases publish `checksums-sha256.txt`
+- the installer verifies the published checksum before replacing the binary
+
+## Upgrades
+
+`clackhouse` checks for new CLI releases at most once per day during interactive use. When a newer build is available, it prints the installer command to rerun for your current channel.
+
+Upgrade stable installs with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh
+```
+
+Upgrade RC installs with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh -s -- --channel rc
+```
 
 ## Usage
 
-The only user-facing command in this first PR is:
+The user-facing commands right now are:
 
 ```bash
+clackhouse init
 clackhouse version
 ```
 

build.rs

@@ -4,16 +4,23 @@ use std::{
     process::Command,
 };
 
+const DEFAULT_AGENT_VERSION_TARGET: &str = "2026.4.2";
+
 fn main() {
     println!("cargo:rerun-if-env-changed=CLACKHOUSE_GIT_COMMIT_SHORT");
     println!("cargo:rerun-if-env-changed=GITHUB_SHA");
+    println!("cargo:rerun-if-env-changed=CLACKHOUSE_AGENT_VERSION_TARGET");
 
     if let Some(git_dir) = git_dir_from_manifest() {
         track_git_inputs(&git_dir);
     }
 
     let version = env::var("CARGO_PKG_VERSION").unwrap_or_else(|_| "0.0.0".to_string());
     let commit_hash = resolve_commit_hash();
+    let agent_version_target = env::var("CLACKHOUSE_AGENT_VERSION_TARGET")
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+        .unwrap_or_else(|| DEFAULT_AGENT_VERSION_TARGET.to_string());
     let version_display = match &commit_hash {
         Some(hash) => format!("{version} [{hash}]"),
         None => version.clone(),
@@ -24,6 +31,7 @@ fn main() {
         commit_hash.as_deref().unwrap_or("")
     );
     println!("cargo:rustc-env=CLACKHOUSE_VERSION_DISPLAY={version_display}");
+    println!("cargo:rustc-env=CLACKHOUSE_AGENT_VERSION_TARGET={agent_version_target}");
 }
 
 fn resolve_commit_hash() -> Option<String> {

docs/getting-started.md

@@ -15,6 +15,12 @@ Or via the install script:
 curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh
 ```
 
+For the latest release candidate instead:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh -s -- --channel rc
+```
+
 To remove the installed binary later:
 
 ```bash
@@ -30,6 +36,7 @@ Release asset format matches `agent`:
 - macOS: `.zip`
 - Linux: `.tar.gz`
 - release page also includes `checksums-sha256.txt`
+- the installer verifies the matching checksum before replacing the binary
 
 ## 2. Verify The Install
 
@@ -39,7 +46,39 @@ Confirm the binary is available:
 clackhouse version
 ```
 
-## 3. Remove The Binary
+## 3. Install The Agent
+
+Install the default pinned `clackhouse-agent` target:
+
+```bash
+clackhouse init
+```
+
+By default the CLI points to agent release `2026.4.2`. `clackhouse version` shows that target. If you intentionally need a different release:
+
+```bash
+clackhouse init --agent-version 2026.4.2
+```
+
+The agent config file and runtime state live under `~/.clackhouse`. The CLI currently leaves config creation alone, which matches the agent's built-in defaults.
+
+## 4. Upgrade The Binary
+
+`clackhouse` checks for new CLI releases at most once per day during interactive use. When it finds a newer release, it prints the installer command to rerun for your current channel.
+
+Upgrade stable installs with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh
+```
+
+Upgrade RC installs with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/install.sh | sh -s -- --channel rc
+```
+
+## 5. Remove The Binary
 
 If you want to cleanly remove the installed CLI binary:
 
@@ -49,4 +88,5 @@ curl -fsSL https://raw.githubusercontent.com/ClackHouse/cli/main/uninstall.sh |
 
 ## Command Summary
 
+- `init [--agent-version VERSION]` installs the `clackhouse-agent` binary
 - `version` prints the CLI version and build metadata

docs/maintainers.md

@@ -29,7 +29,7 @@ just install-hooks
 - `scripts/sync-github-release.sh` and `scripts/previous-release-tag.sh` mirror the `agent` release metadata flow
 - `scripts/install-git-hooks.sh` enables the local git hook workflow
 - `.github/workflows/release.yaml` publishes release assets in the same format as `agent`
-- `.github/workflows/ci.yaml` runs the pre-merge checks inspired by `agent`
+- `.github/workflows/ci.yaml` runs the pre-merge checks and install smoke coverage inspired by `agent`
 
 ## Git Hooks
 
@@ -58,6 +58,9 @@ The CLI uses the same calendar versioning model as the `agent` repository: `YYYY
 - macOS release archives should be published as `clackhouse-<target-triple>.zip`
 - Linux release archives should be published as `clackhouse-<target-triple>.tar.gz`
 - published releases should attach `checksums-sha256.txt`
+- `install.sh` verifies the published checksum before replacing the installed binary
+- `install.sh --channel rc` resolves the latest prerelease build from the GitHub releases feed
+- the CLI update notifier checks at most once per day in interactive sessions and tells users to rerun the installer instead of self-replacing
 - `just release` is the one-command path that may commit `Cargo.toml`/`Cargo.lock`, push `main`, create the release tag, and push the tag
 - `just release-rc` does the same thing for the next prerelease version
 - `just release-version <version>` uses an explicit version instead of the computed one
@@ -75,5 +78,6 @@ The CLI mirrors the `agent` repository's split between CI and release automation
 - `Clippy` runs on Ubuntu and macOS with `cargo clippy --all-targets -- -D warnings`
 - `Test` runs on Ubuntu and macOS with `cargo test --all-targets`
 - `Build` runs a release build on Ubuntu and macOS after the checks pass
+- `Install Smoke` packages the host archive, runs `install.sh`, checks `clackhouse version`, runs `clackhouse init`, and checks `clackhouse-agent version` on Ubuntu and macOS
 
 If you want these jobs to block merges, enable branch protection on `main` in GitHub and require the relevant status checks there.