# CLI overview

## Overview

The gram CLI manages platform resources directly from the terminal. Use it to
authenticate, stage OpenAPI documents and Gram Functions for deployment, push
and monitor deployments, install toolsets as MCP servers in AI agents, and keep
the CLI itself up to date.

## Installation

Install the gram CLI with one of the following methods:

After installation, run the following command to verify that the CLI is installed correctly:

```bash
gram --version
```

Then authenticate:

```bash
gram auth
```

## Authentication

Use `gram auth` to bootstrap an account:

```bash
gram auth
```

Then, inspect the current profile:

```bash
gram whoami
```

The first time `gram auth` runs, it creates and saves a [producer-scoped API
key](/docs/ai-control-plane/org-admin/api-keys) in the dashboard.

## Available commands

<div className="grid md:grid-cols-4 sm:grid-cols-2 gap-4 w-[42rem] mx-auto">
    <a href="/docs/ai-control-plane/reference/command-line/auth">- auth</a>
    <a href="/docs/ai-control-plane/reference/command-line/install">- install</a>
    <a href="/docs/ai-control-plane/reference/command-line/push">- push</a>
    <a href="/docs/ai-control-plane/reference/command-line/stage">- stage</a>
    <a href="/docs/ai-control-plane/reference/command-line/stage-function">- stage function</a>
    <a href="/docs/ai-control-plane/reference/command-line/stage-openapi">- stage openapi</a>
    <a href="/docs/ai-control-plane/reference/command-line/status">- status</a>
    <a href="/docs/ai-control-plane/reference/command-line/update">- update</a>
    <a href="/docs/ai-control-plane/reference/command-line/whoami">- whoami</a>
</div>

## Global CLI options

The following global options are available across CLI commands.

### <code>api-key</code>

Use `api-key` to provide an API key (which must have the producer scope):

```bash
gram push --api-key MY_API_KEY [command options]
```

When this option is not provided, the CLI falls back to using the following
values, in this order:

- The `GRAM_API_KEY` environment variable
- The `secret` field of the current profile in `~/.gram/profile.json`

### <code>project</code>

Use `project` to provide the target project's slug:

```bash
gram push --project my-project [command options]
```

When this option is not provided, the CLI falls back to using the following
values, in this order:

- The `GRAM_PROJECT` environment variable
- The `defaultProjectSlug` field of the current profile in `~/.gram/profile.json`

### <code>org</code>

Use `org` to provide the target organization's slug:

```bash
gram push --org my-org [command options]
```

When this option is not provided, the CLI falls back to using the following
values, in this order:

- The `GRAM_ORG` environment variable
- The organization of the current profile in `~/.gram/profile.json`

### <code>log-level</code>

Use `log-level` to set the base log level (the default is `info`). Because this
is an app-level option, place it before the command name:

```bash
gram --log-level debug [command] [command options]
```

The base log level can also be set via the `GRAM_LOG_LEVEL` environment variable.

### <code>log-pretty</code>

Use `log-pretty` to toggle pretty logging off. (By default, this option is set
to `true`.) Because this is an app-level option, place it before the command
name:

```bash
gram --log-pretty=false [command] [command options]
```

Pretty logging can also be toggled via the `GRAM_LOG_PRETTY` environment variable.

### <code>profile</code>

Use `profile` to provide the profile name to use from `~/.gram/profile.json`.
Because this is an app-level option, place it before the command name:

```bash
gram --profile production [command] [command options]
```

The profile name can also be set via the `GRAM_PROFILE` environment variable.

### <code>help</code>

Use `help` to view the help information for any command:

```bash
gram [command] --help
```

Short form: `-h`

### <code>version</code>

Use `version` to print the version of the gram CLI.

```bash
gram --version
```

Short form: `-v`