Project

Project-level commands. Today this group hosts the ownership-transfer flow; future project-wide actions will land here too.

Ownership transfer

Transfer a project (and everything attached to it — sites, deployments, env vars, domains, databases, storage buckets, auth apps) to another Ghayma user. The flow is two-step: the current owner initiates a transfer, the recipient accepts it via an emailed link within 24 hours.

Audit history stays attributed to the original owner; billing up to the moment of acceptance remains on the original owner’s account.

`ghayma project transfer`

Initiate a transfer of the current project (read from .ghayma.json).


ghayma project transfer [email protected]

The command asks you to type the project name before anything is sent, mirroring the delete flow:


⚠️  Transfer project 'my-project' to [email protected]?
   This will move all deployments, env vars, domains, and other resources.
   Type the project name to confirm:

Output on confirmation:


✅ Transfer initiated.
   Recipient:  [email protected]
   Expires:    2026-04-23T14:02:11Z
   Transfer ID: <uuid>

The recipient has been emailed an accept link. They must accept within 24h.
Cancel before acceptance with: ghayma project transfer cancel

Only the current owner can initiate, and only one transfer can be pending on a project at a time. Initiating a new transfer automatically cancels any previous pending one. You cannot transfer a project to yourself.

The recipient must already have an Ghayma account with the email you specify. If they don’t, ask them to run ghayma register first.

`ghayma project transfer status`

Show the currently pending transfer, if any, for the active project.


ghayma project transfer status

When a transfer is pending:


🔄 Pending transfer:
   To:           [email protected]
   Initiated at: 2026-04-22T14:02:11Z
   Expires at:   2026-04-23T14:02:11Z
   Transfer ID:  <uuid>

Cancel with: ghayma project transfer cancel

When nothing is pending: No pending transfer.

`ghayma project transfer cancel`

Cancel the pending transfer before the recipient accepts.


ghayma project transfer cancel

Output: ✅ Pending transfer cancelled.

If there’s no pending transfer, the command reports the server’s “no pending transfer” error and exits non-zero.

`ghayma project transfer accept`

Accept a transfer using the raw token from the invitation email. The recipient runs this from their logged-in CLI session — your signed-in account’s email must match the recipient email that was used at initiation.


ghayma project transfer accept <token>

The token is the URL-safe base64 string from the accept link in the email; the server hashes and compares it internally. On success:


✅ Transfer accepted. You are now the owner.
   Project ID: <uuid>

Run 'ghayma link' from your repo to wire a local directory to this project,
or 'ghayma status' to see it in your project list.

Most recipients will accept by clicking the link in the email, which opens the dashboard accept page. The CLI command is provided as an alternative for users who prefer terminal flows.

Errors you may see

Error	Cause
`only the project owner can transfer`	You ran `transfer` from a project you don’t own (team projects and transferred projects both check current ownership).
`cannot transfer project to yourself`	The recipient email matches the logged-in account’s email.
`too many transfer attempts on this project in the last 24h`	Hit the per-project rate limit (3 initiates/24h). Pending and cancelled count; accepted and expired don’t.
`too many transfer attempts by this user in the last 24h`	Hit the per-user rate limit (10 initiates/24h).
`project is deleted or suspended; cannot transfer`	The project hit a terminal state between the time you started typing the command and the server accepting it.
`transfer token is invalid or already used`	On `accept`: wrong or reused token. Request a new transfer.
`transfer token has expired`	On `accept`: 24h window has passed. The initiator must re-run `transfer`.
`signed-in user's email does not match the transfer recipient`	On `accept`: you’re logged in as the wrong account. Sign into the account matching the recipient email.
`accepting user has reached their project quota`	On `accept`: the recipient’s plan doesn’t have room for another project. They need to upgrade or delete an existing project first.