# What Is the Role of CatalogClient in kcmd?

> Discover the essential role of CatalogClient in kcmd. This TypeScript class connects the CLI to Google Knowledge Catalog, enabling type-safe entry manipulation and canonical resource identifier normalization.

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

---

**The CatalogClient is the core TypeScript class that bridges the kcmd CLI with Google Knowledge Catalog, exposing type-safe methods for entry manipulation while normalizing resource identifiers to canonical formats.**

The **CatalogClient** in **kcmd** serves as the primary abstraction layer between the command-line synchronization tool and Google Cloud's Knowledge Catalog service (formerly Dataplex). Implemented in the GoogleCloudPlatform/knowledge-catalog repository, this specialized client wraps the generic `ApiClient` to provide Knowledge Catalog-specific operations with consistent resource handling.

## Core Responsibilities of the CatalogClient

### Exposing Dataplex REST Operations

The `CatalogClient` class defined in [`toolbox/mdcode/src/libts/gcp/dataplex.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/gcp/dataplex.ts) (lines 58-131) exposes methods that map directly to Dataplex REST endpoints. These include `getEntryGroup`, `getEntryType`, `getAspectType`, `getEntry`, `lookupEntry`, `createEntry`, `modifyEntry`, `updateEntry`, and `listEntries`. Each method handles the HTTP transport to `https://dataplex.googleapis.com/v1` while providing TypeScript type safety for request and response payloads.

### Normalizing Resource Identifiers

After every API call, the private `_fixEntry` helper method (lines 11-40 in [`dataplex.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/dataplex.ts)) rewrites project numbers to the canonical `projects/<project>/...` form. This normalization ensures that downstream components in the SDK work with consistent resource identifiers regardless of variations in the API response format.

### Configuring API Context

The client initializes with a base URL of `https://dataplex.googleapis.com` and API version `v1`, encapsulating the service configuration. It accepts an `ApiContext` containing credentials and project settings, making it immediately usable by higher-level components without requiring manual endpoint configuration.

## Integration with kcmd Architecture

### CLI Command Initialization

In [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts) (lines 65-87), the CLI entry point constructs a `CatalogClient` from the user-supplied `ApiContext`. Commands such as `kcmd init`, `kcmd pull`, and `kcmd push` instantiate this client and inject it into the synchronization engine, establishing the connection to the Knowledge Catalog service.

### Driving Synchronization Logic

The `CatalogSync` class in [`toolbox/mdcode/src/libts/sync.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/sync.ts) (lines 21-32) receives the `CatalogClient` through its constructor. During pulls, it invokes `lookupEntry` to fetch remote metadata, while push operations utilize `createEntry` and `modifyEntry` to propagate local changes. The client serves as the exclusive transport mechanism for these metadata operations.

### Populating Local Snapshots

When building local representations, the `CatalogSnapshot` class in [`toolbox/mdcode/src/libts/snapshot.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/snapshot.ts) (lines 35-62) calls `getEntryType` and `getAspectType` to populate type metadata. This cached information fuels the manifest and layout layers that store entries on disk, enabling offline manifest operations.

## Working with CatalogClient: Code Examples

### Creating a Client Instance

```typescript
import * as kcmd from 'kcmd';

// Obtain a default API context (credentials, project, etc.)
const ctx = kcmd.gcp.ApiContext.default();

// Build a client that talks to the Knowledge Catalog service
const catalog = new kcmd.gcp.CatalogClient(ctx);

```

### Pulling Entries (as used by `kcmd pull`)

```typescript
// Inside CatalogSync.pull()
const entries = this._snapshot.manifest.source.entries(this._catalog.context);
for await (const entry of entries) {
  const nameParts = entry.name.split('/');
  const res = await this._catalog.lookupEntry(
    nameParts[1],               // project
    nameParts[3],               // location
    entry.name,
    [...this._snapshot.aspectTypes.keys()] // requested aspects
  );
  if (res.status === 200 && res.result) {
    await this._snapshot._storeEntry(res.result);
  }
}

```

### Pushing New Entries (as used by `kcmd push`)

```typescript
// Inside CatalogSync.push()
const exist = await this._catalog.lookupEntry(project, location, entry.name);
if (exist.status !== 200) {
  // Entry does not exist → create it
  const createRes = await this._catalog.createEntry(
    project,
    location,
    entryGroup,
    entryId,
    entry
  );
}

```

### Listing Entries (as used by `kcmd status`)

```typescript
// Inside CatalogSync.status()
for await (const entry of this._catalog.listEntries(project, location, entryGroup)) {
  console.log(entry.name);
}

```

## Summary

- The **CatalogClient** in [`toolbox/mdcode/src/libts/gcp/dataplex.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/gcp/dataplex.ts) serves as the dedicated bridge between **kcmd** and Google Knowledge Catalog, wrapping the generic `ApiClient` with domain-specific methods.
- It provides **type-safe access** to Dataplex REST endpoints including `lookupEntry`, `createEntry`, and `modifyEntry` while targeting `https://dataplex.googleapis.com/v1`.
- The **`_fixEntry`** helper ensures resource name consistency by normalizing project identifiers to canonical formats after every API call.
- **CLI commands** instantiate the client in [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts) and pass it to the sync engine, which uses it exclusively for metadata operations.
- The **snapshot builder** relies on `getEntryType` and `getAspectType` to cache type metadata locally, supporting offline manifest operations.

## Frequently Asked Questions

### What is the relationship between CatalogClient and ApiClient in kcmd?

The **CatalogClient** is a specialized wrapper around the generic **ApiClient**. While `ApiClient` handles raw HTTP transport and authentication, `CatalogClient` adds Knowledge Catalog-specific logic including endpoint paths, resource normalization via `_fixEntry`, and typed methods for entry operations.

### How does CatalogClient handle resource name normalization?

After each API call, the private **`_fixEntry`** method (defined in [`toolbox/mdcode/src/libts/gcp/dataplex.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/gcp/dataplex.ts) lines 11-40) processes the response to rewrite project numbers into canonical `projects/<project>/...` identifiers. This ensures consistent resource naming throughout the SDK regardless of API response variations.

### Which kcmd commands rely on CatalogClient?

The **`kcmd init`**, **`kcmd pull`**, **`kcmd push`**, and **`kcmd status`** commands all rely on `CatalogClient`. The CLI constructs the client in [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts) (lines 65-87) and passes it to `CatalogSync`, which uses it for all remote operations including listing, looking up, creating, and modifying entries.

### Where is the CatalogClient class defined in the source code?

The `CatalogClient` class is defined in **[`toolbox/mdcode/src/libts/gcp/dataplex.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/gcp/dataplex.ts)** in the GoogleCloudPlatform/knowledge-catalog repository. This file contains the class implementation along with the `_fixEntry` helper and all CRUD methods for Knowledge Catalog entities.