# gram push

The `push` command deploys the staged sources in a deployment configuration
to the target project.

For more information on staging sources, see the [`gram stage`
reference](/docs/ai-control-plane/reference/command-line/stage).

<Callout type="info">
    The `gram push` command requires an API key, an organization slug, and a
    project slug. After running `gram auth`, these values come from the local
    profile. For more information on these values, see the [global CLI
    options](/docs/ai-control-plane/reference/command-line#global-cli-options).
</Callout>

## Usage

```bash
gram push --config gram.deploy.json
```

After the deployment completes, the command prints a link to view the
deployment in the dashboard. If the deployment fails, check its logs with
[`gram status`](/docs/ai-control-plane/reference/command-line/status).

## Deployment file

The deployment file contains the configuration for all sources that will be
pushed. Below is a sample deployment file:

```json filename="gram.deploy.json"
{
  "schema_version": "1.0.0",
  "type": "deployment",
  "sources": [
    {
      "type": "openapiv3",
      "location": "/path/to/spec.yaml",
      "name": "My API",
      "slug": "my-api"
    }
  ]
}
```

<Callout type="info" title="Note on slugs">
    Names and slugs must be unique across all sources in the target project.
</Callout>

## Options

### <code>config</code> (required)

This specifies the path to the deployment file.

```bash
gram push --config ./path/to/gram.deploy.json [command options]
```

### <code>method</code>

This specifies the deployment method for handling existing artifacts. If not specified, it defaults to `merge`.

- **`merge`:** The deployment merges with any existing deployment artifacts in the project.
- **`replace`:** The deployment replaces any existing deployment artifacts in the project.

```bash
gram push --method replace [command options]
```

### <code>idempotency-key</code>

This adds a unique key to identify the deployment request for idempotency. It ensures the same deployment isn't applied multiple times if the command is run
again with the same key. It only applies when the method is `replace`.

```bash
gram push --idempotency-key unique-deployment-id [command options]
```

### <code>skip-poll</code>

Use this option to skip polling for deployment completion and return immediately. By default, this is set to `false`.

```bash
gram push --skip-poll [command options]
```