Python SDK - PyGEAI provides the geai migrate clone-project Command Line that allows you to clone and migrate Projects and their resources.
You can migrate the following:
Available options are grouped into:
- Required arguments
- Optional arguments
- Migration flags
- --from-api-key <key>: An API token generated for each Project.
- --from-project-id <id>: ID of the source Project to migrate from.
- --from-instance <url>: The base URL for your Globant Enterprise AI installation, for example, https://api.saia.ai or the value provided to you.
- --from-org-key <key>: Organization scope API key (REQUIRED when creating projects or migrating usage limits).
- --to-api-key <key>: Project scope API key for the destination instance. REQUIRED when using --to-project-id (existing project). OPTIONAL when creating a new Project (auto-generated if not provided).
- --to-org-key <key>: Organization scope API key for the destination (REQUIRED when creating Projects or migrating usage limits).
- --to-project-id <id>: Destination Project ID (use this to migrate to an existing Project). REQUIRED: --to-api-key must also be provided. MUTUALLY EXCLUSIVE with --to-project-name and --admin-email.
- --to-project-name <name>: Name for the new destination project (when specified with --admin-email, creates a new Project). MUTUALLY EXCLUSIVE with --to-project-id.
- --admin-email <email>: Admin email for the new Project (required when creating a new Project with --to-project-name).
- --to-instance <url>: URL of the destination (defaults to source instance if omitted).
- --from-organization-id <id>: Organization ID in the source (required for usage limits and file migration).
- --to-organization-id <id>: Organization ID in the destination (required for usage limits and file migration).
- --all: Migrate all available resource types (Agents, Tools, Agentic Processes, Tasks, Usage limits, RAG Assistants, Files, Secrets).
- --agents <all|id1,id2,...>: Migrate all Agents or specific Agents by ID (comma-separated).
- --tools <all|id1,id2,...>: Migrate all Tools or specific Tools by ID (comma-separated).
- --agentic-processes <all|id1,id2,...>: Migrate all Agentic Processes or specific Agentic Processes by ID (comma-separated).
- --tasks <all|id1,id2,...>: Migrate all Tasks or specific Tasks by ID (comma-separated).
- --usage-limits <all|id1,id2,...>: Migrate all Usage limits or specific Usage limits by ID (comma-separated).
- --rag-assistants <all|id1,id2,...>: Migrate all RAG Assistants or specific RAG Assistants by ID (comma-separated).
- --files <all|id1,id2,...>: Migrate all Files or specific Files by ID (comma-separated).
- --secrets <all|id1,id2,...>: Migrate all Secrets or specific Secrets by ID (comma-separated).
- --stop-on-error <0|1> or --soe <0|1>: Control migration behavior on errors. Set to 1 (default) to stop migration on first error, or 0 to continue migrating remaining resources even if some fail.
Required credentials and API token scopes depend on whether you migrate into a new Project or an existing Project. The following sections cover what you need for each scenario:
- Prerequisites
- API Token scopes
- Migration scenarios and required keys
Before migrating, you need:
- Source credentials: API key and instance URL for the source Project.
- Destination credentials: API key and URL (can be the same as source).
- Project identifiers: Source Project ID.
- Admin email: Required when creating a new destination Project.
Different migration operations require different API token scopes:
- Organization Scope Tokens
- Project Scope Tokens
Required for operations that create or manage Projects and Organization-level resources:
- Project Creation: Creating new projects requires organization scope API keys (--from-org-key and --to-org-key).
- Usage Limit Migration: Managing usage limits requires organization scope API keys.
For more information, see Organization API and Usage Limits API.
Required for the following operations within a Project:
- Agent Migration
- Tool Migration
- Agentic Process Migration
- Task Migration
- RAG Assistant Migration
- File Migration
- Secret Migration
The required API keys depend on whether you're creating a new Project or migrating to an existing one:
When using --to-project-name and --admin-email:
- --from-api-key: Project scope token for reading source resources.
- --from-org-key: Organization scope token (REQUIRED for Project creation).
- --to-org-key: Organization scope token for destination (REQUIRED, or use --from-org-key for same instance).
- --to-api-key: OPTIONAL - If not provided, a Project scope API key will be automatically created for the new Project.
The migration process will:
- Create the new Project using Organization scope keys.
- Automatically generate a Project scope API key for the new Project.
- Use the generated key to migrate all resources.
When using --to-project-id:
- --from-api-key: Project scope token for reading source resources (REQUIRED).
- --to-api-key: Project scope token for writing to destination Project (REQUIRED).
- Organization scope keys are NOT needed for resource migration.
Note: When migrating to an existing Project (using --to-project-id), you must provide --to-api-key. This is a Project scope token that has write access to the destination Project.
- Test first: Run migrations in a development environment before production.
- Use --all for complete clones: Use it when you need a full backup or a full Project copy.
- Verify credentials: Confirm API keys and instance URLs before running the command.
- Monitor progress: Review discovery counts and status messages during execution.
- Check results: Validate the migration summary after completion.
- Use incremental migrations for large Projects: Migrate resource types in separate runs when needed.
- Document migrations: Record what you migrated and when.
When you use all for any resource type, the migration process:
- Connects to the source instance.
- Lists all available resources of that type.
- Filters resources with valid IDs/names.
- Creates migration strategies for each discovered resource.
- Displays the count of discovered resources.
For example:
geai migrate clone-project ... --agents all
This command produces output similar to the following:
Discovered 15 agents
Migrating agents...
[Progress indicators]
The migration process validates inputs before starting and reports errors during execution.
- Invalid API keys or instance URLs return clear error messages.
- Missing required parameters are detected before the migration starts.
- By default, a failure in one resource stops the migration (--stop-on-error 1).
- Use --stop-on-error 0 to continue migrating remaining resources even if some fail.
- The final summary includes a success or failure status for each migrated resource.
- API rate limits can affect large migrations.
- Some resource dependencies can require a specific migration order.
- Cross-instance migrations require network connectivity between instances.
- Some resource types can include instance-specific configuration.
Since version 2026-01.