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

# Push

> Upload a local Cognee knowledge graph to a remote Cognee instance.

## What is the push operation

The `.push` operation uploads a local dataset's already-built knowledge graph to Cognee Cloud or another remote Cognee instance.

Unlike a raw-data sync, `push()` ships the graph you already extracted locally. Cognee exports the dataset to a [COGX archive](/core-concepts/further-concepts/cogx), uploads it, and imports it on the remote instance so entities and relationships can be preserved.

It is available from both the Python SDK and the CLI:

```python theme={null}
await cognee.push("onboarding")
```

```bash theme={null}
cognee push onboarding
```

## Where push fits

* Use `push()` when you have built a graph locally and want the same graph available remotely.
* Use it when local graph extraction has already done the expensive LLM work and you want the remote side to preserve that result.
* Use it after [Remember](/core-concepts/main-operations/remember) or [Cognify](/core-concepts/main-operations/legacy-operations/cognify), not before them.
* Use [syncing a local instance](/cognee-cloud/connections/syncing-local-instance) instead when you want to send raw data and let the remote instance rebuild memory itself.

## What happens under the hood

1. **Resolve the local dataset** - Cognee finds the dataset by name or UUID and checks that it can be read.
2. **Export the graph** - the dataset's graph is exported as a COGX archive.
3. **Upload the archive** - the archive is sent to the configured remote Cognee instance.
4. **Import remotely** - the remote instance imports the archive into the target dataset.
5. **Report the result** - Cognee returns the remote status, target dataset, graph size, and any pipeline run id.

<Note>
  The dataset must already have a knowledge graph. If the export finds no graph nodes, run `cognee.remember()` or `cognee.cognify()` on the dataset first.
</Note>

## Import modes

`push()` supports three remote import modes:

| Mode        | Remote behavior                                                     | LLM calls |
| ----------- | ------------------------------------------------------------------- | --------- |
| `preserve`  | Map the exported entities and facts directly into the remote graph  | None      |
| `hybrid`    | Preserve the exported graph and also cognify the raw content        | Yes       |
| `re-derive` | Ignore the exported graph and rebuild from the raw content remotely | Yes       |

The default mode is `preserve`, which is the graph-preserving path.

## Authentication

`push()` uses the same remote credential stack as `cognee.serve()`:

1. Explicit `url` and `api_key` arguments
2. An active `cognee.serve()` connection
3. `COGNEE_SERVICE_URL` and `COGNEE_API_KEY` environment variables
4. Saved credentials from a previous `serve` login

If no remote credentials are available, `push()` raises an authentication error instead of uploading anywhere implicitly.

## Examples and details

<Accordion title="Push with the Python SDK" defaultOpen>
  ```python theme={null}
  import cognee

  # Build a graph locally.
  await cognee.remember("docs/handbook.pdf", dataset="onboarding")

  # Log in once so push can reuse the remote credentials.
  await cognee.serve()

  # Push the local graph to the remote dataset with the same name.
  result = await cognee.push("onboarding")

  print(result.target_dataset)
  print(result.num_nodes, result.num_edges)
  ```
</Accordion>

<Accordion title="Push with the CLI">
  ```bash theme={null}
  # Build local memory first.
  cognee remember docs/handbook.pdf --dataset-name onboarding

  # Log in once.
  cognee serve

  # Push the graph to the remote instance.
  cognee push onboarding
  ```
</Accordion>

<Accordion title="Push to a different remote dataset">
  Use `target_dataset` when the remote dataset should have a different name from the local dataset.

  ```python theme={null}
  await cognee.push(
      "onboarding",
      target_dataset="prod_onboarding",
  )
  ```

  ```bash theme={null}
  cognee push onboarding --target-dataset prod_onboarding
  ```
</Accordion>

<Accordion title="Run large imports in the background">
  For larger graphs, schedule the remote import in the background and track the returned pipeline run id.

  ```python theme={null}
  result = await cognee.push(
      "onboarding",
      run_in_background=True,
  )

  print(result.pipeline_run_id)
  ```

  ```bash theme={null}
  cognee push onboarding --background
  ```
</Accordion>

<Accordion title="Push to an explicit remote instance">
  If you do not want to rely on a saved `serve` login, pass the remote URL and API key directly.

  ```python theme={null}
  await cognee.push(
      "onboarding",
      url="https://your-instance.cognee.ai",
      api_key="your-api-key",
  )
  ```

  ```bash theme={null}
  cognee push onboarding \
    --url https://your-instance.cognee.ai \
    --api-key your-api-key
  ```
</Accordion>

## See also

* [COGX archives](/core-concepts/further-concepts/cogx)
* [Syncing a local instance](/cognee-cloud/connections/syncing-local-instance)
* [Cognee CLI](/cognee-cli/overview)