> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morphllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitMorph

> Git platform for AI-native development

GitMorph is a git platform built for AI coding agents. Host repos, mirror from GitHub, search code with WarpGrep, and manage everything from the CLI or SDK.

## Install the CLI

<Tabs>
  <Tab title="Shell (recommended)">
    ```bash theme={null}
    curl -fsSL https://gitmorph.com/cli/install.sh | sh
    ```

    Installs a single binary to `~/.local/bin/gm` (or `/usr/local/bin/gm`). Supports macOS and Linux, both ARM64 and x86\_64.
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew install morphllm/tap/gm
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g @morphllm/cli
    ```
  </Tab>
</Tabs>

## Authenticate

```bash theme={null}
gm auth login
```

This prompts for a personal access token. Generate one at [gitmorph.com/user/settings/security](https://gitmorph.com/user/settings/security).

You can also authenticate via environment variables:

```bash theme={null}
export GM_TOKEN="your-token"
export GM_HOST="gitmorph.com"   # optional, defaults to gitmorph.com
```

Check your auth status:

```bash theme={null}
gm auth status
```

## Setup

After logging in, run setup to configure SSH access and upload your coding profile:

```bash theme={null}
gm setup
```

This does two things:

1. Generates an SSH key (`~/.ssh/id_ed25519`) and registers it with the server
2. Scans your `CLAUDE.md` files, sanitizes secrets/paths, and uploads your personality profile

Both steps are also available as standalone commands:

```bash theme={null}
gm ssh-key setup          # SSH key only
gm personality upload     # Profile only (use --dry-run to preview)
```

## Basic CLI Usage

The `gm` CLI mirrors the GitHub `gh` CLI in UX and argument patterns.

```bash theme={null}
# Repositories
gm repo list
gm repo create my-project --private
gm repo clone OWNER/REPO

# Issues
gm issue list
gm issue create -t "Bug report" -b "Steps to reproduce..."
gm issue view 42

# Pull Requests
gm pr list
gm pr create -t "Add feature" -B main
gm pr merge 10 -s              # squash merge

# Code search (WarpGrep)
gm search code OWNER/REPO "Where is the auth logic"

# Mirror a GitHub repo
gm repo fork https://github.com/org/repo
```

Most commands that operate on a repo accept `-R OWNER/REPO`. If omitted, the CLI infers the repo from the current directory's git remote.

All list/view commands support `--json` for structured output and `--jq` for filtering:

```bash theme={null}
gm repo list --json full_name,stars_count
gm pr list --json --jq ".[] | .title"
```

See the [full CLI reference](/sdk/components/repos/git-operations#cli-reference) for all commands.

## Install the SDK

The TypeScript SDK provides programmatic access to GitMorph.

```bash theme={null}
npm install @morphllm/morph-git-sdk
```

## SDK Quick Start

```typescript theme={null}
import { GitMorph } from "@morphllm/morph-git-sdk";

const gm = new GitMorph({ token: "your-token" });

// Get a repo handle
const repo = gm.repo("tejas/my-project");

// Read a file
const file = await repo.readFile("src/index.ts");
console.log(file.content);

// Read specific lines
const snippet = await repo.readFile("src/auth.ts", {
  lines: [{ start: 10, end: 25 }],
});

// Search code
const results = await repo.grep({ pattern: "handleAuth" });
for (const match of results.matches) {
  console.log(`${match.path}:${match.lineNumber} ${match.lineContent}`);
}

// List files with glob
const tsFiles = await repo.glob({
  patterns: ["**/*.ts"],
  prefix: "src/",
});
```

### Authentication

The SDK resolves credentials in this order:

1. Constructor argument: `new GitMorph({ token: "..." })`
2. Environment variable: `GM_TOKEN`
3. Config file: `~/.config/gm/config.json` (written by `gm auth login`)

```typescript theme={null}
// Explicit token
const gm = new GitMorph({ token: "your-token" });

// Custom host
const gm = new GitMorph({
  token: "your-token",
  host: "code.morphllm.com",
});

// Reads from GM_TOKEN env or ~/.config/gm/config.json
const gm = new GitMorph();
```

### Mirror a GitHub Repo

Import a repository from GitHub into GitMorph:

```typescript theme={null}
const { repository, repo } = await gm.mirror(
  "https://github.com/org/my-repo",
  {
    source: "github",
    private: true,
    issues: true,
    pullRequests: true,
    labels: true,
  }
);

console.log(`Mirrored to: ${repository.html_url}`);

// Start working with it immediately
const files = await repo.listDir({ recursive: true });
```

### Cross-Repo Code Search

Search across all your repositories:

```typescript theme={null}
const results = await gm.grepAll({
  pattern: "TODO",
  language: "typescript",
  limit: 20,
});

for (const match of results.matches) {
  console.log(`${match.repoName}/${match.filename}`);
  for (const line of match.lines) {
    console.log(`  L${line.num}: ${line.content}`);
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="SDK API Reference" icon="code" href="/sdk/components/repos/git-operations">
    All SDK methods, types, and options
  </Card>

  <Card title="WarpGrep" icon="search" href="/sdk/components/warp-grep/index">
    Semantic code search for agents
  </Card>
</CardGroup>