# PAM Project Import/Export

## PAM Project Import and Export

Commander supports round-trip import and export of PAM project configurations as JSON. Use `pam project export` to capture an existing project and `pam project import` to apply it to the same or a different tenant.

> **Applies to:** Keeper Commander 17.3+ (PR #2006 for export, PR #2005 for import dedup guard, merged 2026-04-30)

***

### Commands

| Command              | Description                                  |
| -------------------- | -------------------------------------------- |
| `pam project export` | Export a PAM project configuration to JSON   |
| `pam project import` | Import a PAM project configuration from JSON |

***

### pam project export

Walks the vault graph for a given PAM project configuration UID and emits a JSON document that is directly re-importable via `pam project import`.

#### Syntax

```
pam project export -p <config-uid> [--output <file>]
```

#### Parameters

| Parameter         | Required | Description                                                 |
| ----------------- | -------- | ----------------------------------------------------------- |
| `-p <config-uid>` | Yes      | UID of the PAM project configuration to export              |
| `--output <file>` | No       | Write JSON to this file path. If omitted, prints to stdout. |

#### Output schema

The exported JSON matches `PROJECT_IMPORT_JSON_TEMPLATE` exactly and is always re-importable without modification:

```json
{
  "tool_version": "commander-export-1.0",
  "project": { ... },
  "shared_folder_users": [ ... ],
  "shared_folder_resources": [ ... ],
  "pam_configuration": { ... },
  "pam_data": {
    "resources": [ ... ],
    "users": [ ... ]
  }
}
```

| Field                     | Description                                                            |
| ------------------------- | ---------------------------------------------------------------------- |
| `tool_version`            | Identifies the export generator; activates generator-aware import path |
| `project`                 | PAM project metadata (name, node, shared folder UIDs)                  |
| `shared_folder_users`     | Users with access to the shared folder                                 |
| `shared_folder_resources` | Resources linked to the shared folder                                  |
| `pam_configuration`       | Full PAM configuration (gateway, rotation policy, etc.)                |
| `pam_data.resources`      | PAM-managed resources (machines, databases, directories)               |
| `pam_data.users`          | PAM-managed users, de-duplicated across resources                      |

#### Design properties

* **Deterministic output** — `sort_keys=True` ensures stable JSON suitable for git diffs and drift detection
* **Idempotent re-import** — resource UIDs are derived from Keeper record UIDs, which are stable across exports
* **User de-duplication** — users shared across multiple resources appear once in `pam_data.users`

#### Examples

Export to stdout:

```
My Vault> pam project export -p f6e5d4c3
{
  "tool_version": "commander-export-1.0",
  "project": { ... },
  ...
}
```

Export to a file for later import or version control:

```
My Vault> pam project export -p f6e5d4c3 --output project-backup.json
```

Round-trip — export from one tenant, import to another:

```bash
keeper pam project export -p f6e5d4c3 --output project.json
# on target tenant:
keeper pam project import --filepath project.json
```

***

### pam project import

Imports a PAM project from a JSON file. Supports re-importing an export from `pam project export` or a manually authored import document.

#### Syntax

```
pam project import --filepath <file> [--dry-run]
```

#### Parameters

| Parameter           | Required | Description                                 |
| ------------------- | -------- | ------------------------------------------- |
| `--filepath <file>` | Yes      | Path to the JSON import document            |
| `--dry-run`         | No       | Validate and preview without making changes |

#### Duplicate UID guard (PR #2005)

`pam project import` now rejects import documents that contain duplicate `uid` values before creating any records.

**Before this fix:** Duplicate UIDs were silently preserved, producing an ambiguous dependency graph and incorrect DAG links during record creation.

**After this fix:** If any `uid` value appears more than once across resources and users, the import aborts with a clear error message listing the duplicates. Zero records are created.

```
My Vault> pam project import --filepath bad-project.json
ERROR: Duplicate uid values found in import document: ['abc123', 'def456']
Import aborted. No records were created.
```

Valid imports with unique UIDs continue to work unchanged.

#### Import document format

Import documents must follow the same schema as `pam project export` output. Key rules:

* All `uid` values across `pam_data.resources` and `pam_data.users` must be unique
* `tool_version` is optional; its presence activates generator-aware import behaviour
* UIDs should be stable base64-URL-encoded 16-byte values; the importer will generate them if absent

#### Example

```
My Vault> pam project import --filepath project.json
Importing PAM project from project.json...
  Created PAM configuration: prod-web (uid: f6e5d4c3)
  Created resource: web-server-01 (uid: a1b2c3d4)
  Created user: svc-deploy (uid: 9a8b7c6d)
Import complete: 1 configuration, 1 resource, 1 user.
```

***

### Workflow: environment promotion

A common use case is promoting a PAM project from a staging tenant to production:

```bash
# 1. Export from staging
keeper --config ~/.keeper/staging.json \
  pam project export -p <staging-config-uid> --output staging-project.json

# 2. Review the export (it's stable JSON — diff is clean)
git diff HEAD staging-project.json

# 3. Commit for audit trail
git add staging-project.json && git commit -m "snapshot: PAM project pre-promotion"

# 4. Import to production
keeper --config ~/.keeper/production.json \
  pam project import --filepath staging-project.json
```

***

### Notes

* `pam project export` requires the authenticated user to have admin access to the PAM configuration and shared folder.
* The export walks the vault graph live — ensure Commander has an up-to-date vault sync before exporting (`sync` command).
* `tool_version: "commander-export-1.0"` in exported files activates a dedicated import branch that handles UIDs generated by Commander. Manually authored files without `tool_version` use the standard import path.
* The duplicate UID guard in `pam project import` runs after the UID-normalisation pass, so externally supplied valid unique UIDs continue to work unchanged.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/en/keeperpam/commander-cli/command-reference/keeperpam-commands/pam-project-import-export.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.