Commands Reference

The Bloc CLI is a unified terminal client used to search, deploy, and manage local AI environment runs.

Usage

bloc [command] [flags]

To see help options for any command, run:

bloc [command] --help

---

Registry & Authentication Commands

bloc login

Authenticates your local terminal session with your Bloc Hub account using GitHub OAuth device flow.

bloc login

• Storage: Credentials are saved securely on your local filesystem under ~/.config/bloc/auth.json.
• Requirements: Access to a web browser to confirm the GitHub verification code.

bloc logout

Clears your locally stored Hub credentials and terminates the session.

bloc logout

bloc search [query]

Search the public recipe registry hosted on bloc-theta.vercel.app.

bloc search deepseek --vram 8GB --platform cuda

• Arguments: Optional string query to match recipe names, descriptions, or tags.
• Flags:
  • --vram <value>: Filter results by minimum VRAM requirements (e.g. 8GB, 16GB, Unified).
  • --platform <value>: Filter by platform: cuda (NVIDIA), metal (macOS), rocm (AMD), or cpu.
  • --limit <number>: Limit the number of search results displayed (default: 20).

---

Deployment Commands

bloc deploy [author/recipe]

Fetches a recipe manifest from the registry, downloads the required weights (either GGUF or Hugging Face repository files), validates your local execution capabilities, runs pre-run setup scripts, and starts the API server.

bloc deploy arnav/qwen3-30b-moe-8gb-cpu-offload

• Arguments: Required recipe path in the format {username}/{recipe-name}.
• Flags:
  • --dry-run: Build and print the complete execution command (including all computed engine flags) without actually launching the process.
  • --no-telemetry: Disable session performance and metrics reporting for this run.
  • --runtime <value>: Override the recipe's declared execution runtime environment. Supported runtimes: native (local OS process) or docker (containerized).

---

Cache & System Management

bloc cache

Manage the local cache directory (~/.cache/bloc).

• bloc cache status: Show local cache directory locations and size breakdown across GGUF models, Hugging Face repos, Python runtimes, and temp download files.
• bloc cache prune: Wipe the entire cache directory. Clears all cached weights, Python environments, and temp files (requires user confirmation).

bloc images

Manage Docker container images pulled by containerized recipes.

• bloc images list: List local container images with vllm in their repository name, along with their image IDs, tags, sizes, and creation dates.
• bloc images prune: Interactively select and remove cached Docker images to reclaim disk space.

bloc runtime

Manage versioned local engines and execution runtime environments.

• bloc runtime status: Scan your system PATH for llama-server and docker, verify Docker daemon access, check for installed Python virtual environments, and test if the NVIDIA Container Toolkit GPU passthrough is functional.
• bloc runtime list: List all locally installed python virtual environments created by native vLLM deployments with Python version, installation date, and size.
• bloc runtime prune: Interactively select and delete cached versioned python environments.

bloc models

List all locally cached model weight files (GGUFs) downloaded by the CLI. Displays filenames, sizes in gigabytes, download dates, and total cache folder size.

bloc models

bloc models clear

Delete cached single-file GGUF model weights to reclaim disk space.

bloc models clear

• Prompts for confirmation before deleting files.

---

Utility Commands

bloc telemetry [on|off|show]

Configure or check anonymous telemetry reporting.

bloc telemetry show

• Arguments:
  • on: Enable telemetry.
  • off: Disable telemetry.
  • show: Print current configuration.
• Environment Override: You can also set BLOC_NO_TELEMETRY=1 in your environment variables to disable all telemetry permanently.

---

System Commands

bloc update

Atomically check for and update your bloc CLI executable to the latest release from the GitHub repository.

bloc update

bloc version

Print the currently installed Bloc CLI version, build commit, and build date.

bloc version