# What Are the Available kcmd CLI Commands? A Complete Guide to Knowledge Catalog

> Explore the kcmd CLI commands init pull push status and mcp to manage metadata snapshots and synchronize with Google Cloud Knowledge Catalog. Your complete guide.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: how-to-guide
- Published: 2026-07-15

---

**The `kcmd` CLI provides five primary commands—`init`, `pull`, `push`, `status`, and `mcp`—for managing metadata snapshots and synchronizing with Google Cloud's Knowledge Catalog.**

The `kcmd` command-line interface is the primary tool for interacting with the Knowledge Catalog project in the GoogleCloudPlatform/knowledge-catalog repository. Written in TypeScript and built on the `cac` framework, this CLI enables users to initialize local snapshots, sync metadata with BigQuery and Dataplex, and expose operations via an MCP server.

## Core kcmd CLI Commands Overview

The command surface is defined in [`toolbox/mdcode/docs/design.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/design.md) (lines 92-98) and implemented in [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/main.ts) (lines 9-14). The following commands comprise the complete `kcmd` interface:

| Command | Description |
|---------|-------------|
| `kcmd init` | Create a local snapshot from BigQuery datasets, Dataplex EntryGroups, or Knowledge Bases |
| `kcmd pull` | Pull latest catalog metadata into the local snapshot (read-only) |
| `kcmd push` | Push local changes back to the catalog with conflict resolution options |
| `kcmd status` | Show summary of local modifications compared to remote catalog |
| `kcmd mcp` | Launch the MCP (Metadata Control Plane) server for external agent integration |

## Detailed Command Reference

### kcmd init

The `init` command establishes a local snapshot from various Google Cloud data sources. According to the implementation in [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts), it supports three mutually exclusive flags:

- `--bigquery-dataset <id>`: Initialize from a BigQuery dataset
- `--entry-group <id>`: Initialize from a Dataplex EntryGroup
- `--kb <id>`: Initialize from a Knowledge Base

```bash
kcmd init --bigquery-dataset my-project.my_dataset

```

### kcmd pull

The `pull` command retrieves the latest metadata from the remote catalog without modifying local files. The `--dry-run` flag allows you to preview changes before applying them.

```bash
kcmd pull --dry-run

```

### kcmd push

The `push` command uploads local modifications back to the catalog. As implemented in [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts) (lines 28-87), it supports three options:

- `--dry-run`: Preview changes without applying
- `--validate-only`: Validate local changes without pushing
- `--force`: Overwrite remote conflicts forcibly

```bash
kcmd push --force

```

### kcmd status

Displays a summary of local modifications compared with the remote catalog state. This read-only operation helps identify pending changes before pushing.

```bash
kcmd status

```

### kcmd mcp

Launches the Metadata Control Plane (MCP) server that exposes synchronization operations as tools for external agents. This enables programmatic access to Knowledge Catalog operations.

```bash
kcmd mcp

```

## Implementation Architecture

The CLI entry point in [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/main.ts) registers all commands using the `cac` framework, while the actual command implementations reside in [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts). The [`toolbox/mdcode/package.json`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/package.json) file declares the `kcmd` binary and build scripts, making the tool available globally when installed.

## Summary

- **`kcmd`** provides five primary commands for Knowledge Catalog management: `init`, `pull`, `push`, `status`, and `mcp`
- **Initialization** supports BigQuery datasets, Dataplex EntryGroups, and Knowledge Bases via specific flags
- **Synchronization** uses `pull` for read-only updates and `push` with `--dry-run`, `--validate-only`, and `--force` options for safe deployment
- **MCP server** enables external agent integration through the `kcmd mcp` command
- **Source files** are located in [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/main.ts) (entry point) and [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts) (implementation)

## Frequently Asked Questions

### What is the primary purpose of kcmd?

The `kcmd` CLI serves as the command-line interface for the GoogleCloudPlatform/knowledge-catalog project, enabling users to create local snapshots of BigQuery and Dataplex metadata, synchronize changes bidirectionally, and expose catalog operations to external agents via the MCP server.

### How do I initialize a local snapshot with kcmd?

Use the `kcmd init` command with one of three source flags: `--bigquery-dataset`, `--entry-group`, or `--kb`. This command creates a local representation of the specified Google Cloud resource, as defined in [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts).

### What does the --dry-run flag do in kcmd?

The `--dry-run` flag simulates operations without making actual changes. It works with both `kcmd pull` and `kcmd push`, allowing you to preview metadata updates or local changes before committing them to the remote catalog.

### How does kcmd handle synchronization conflicts?

When pushing local changes, use the `--force` flag to overwrite remote conflicts, or `--validate-only` to check for errors without pushing. The `kcmd status` command shows pending modifications before you execute a push operation.