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

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 (lines 92-98) and implemented in 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, 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

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.

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 (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

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.

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.

kcmd mcp

Implementation Architecture

The CLI entry point in 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. The 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 (entry point) and 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}