platform-trial-org-create

What this skill does

Creates a Salesforce trial org by inserting a SignupRequest sObject with the sf CLI — the same request the Trialforce/developer web signup form issues under the hood. There is no bespoke signup endpoint: signup = inserting a SignupRequest (key prefix 0SR) against an authenticated host org (a Trialforce Source Org / Env Hub / partner org that is entitled to create trial orgs).

The flow is two CLI calls: (1) create the SignupRequest, (2) read it back to pick up the assigned org id (creation is asynchronous — the org id appears shortly after the insert).

Prerequisites — confirm before executing

1. Authenticated host org — always confirm which one, explicitly. You are signing up from an authenticated host org, not anonymously. The sf CLI operates against an org you have already logged into once (sf org login web, or sf org login).

   Always pass an explicit --target-org (-o) with the host org's alias or username on every command, and confirm the target with the user before creating — even if a default org is configured. Creating a SignupRequest is a real provisioning action; do not let it run against whatever org happens to be the default.

   • Do not rely on the default-org fallback. With no -o, the CLI resolves the target from --target-org → SF_TARGET_ORG env var → local then global target-org config, and errors (NoDefaultEnvError) if none is set — it never auto-picks among your connected orgs. That default may be an unrelated dev/scratch org, so an omitted -o is either wrong-org or a hard failure. Never omit it.
   • The user may have many authenticated orgs. Run sf org list and, if the intended host org is ambiguous or not provided, ask the user which alias/username to use. Do not guess.
   • Verify the chosen org is Connected in sf org list before creating (stale refresh tokens / expired certs show as error states, not Connected).
   • Never invent credentials.

2. Host org must be entitled to create trial orgs, and the invoking user must have sufficient access on it. The skill does not run a separate permission check — the sf data create record call (Step 1) is the definitive gate, and the same API enforcement is what a check would rely on. If the org is not entitled, the SignupRequest entity is not exposed and the create fails with a non-zero status and name/code of NOT_FOUND ("The requested resource does not exist") or INVALID_TYPE ("sObject type 'SignupRequest' is not supported"). This case is handled in Step 1's error table.

   When it happens, stop (it is not retryable from the CLI) and report to the user: (a) the raw CLI error as-is — the exact name/errorCode and message the CLI returned, verbatim — and (b) that they should reach out to Salesforce support to get the org enabled for trial-org creation, then try again. Do NOT diagnose or name which permission is missing — just surface the raw error and point them to support.

Required Inputs — collect from the invoking user before any create

Prompt the user for these and do NOT proceed until all are provided. Do not invent values. Ask for each one; if the user is unsure about a field, guide them using the "If the user is unsure" column before moving on.

Always required (5) — these are required="true" on the SignupRequest entity (FirstName is listed here for prompting convenience but is optional):

Input	Notes	If the user is unsure
LastName	Admin user's last name. Max 80 chars.	Any surname for the new org's admin user; it's just the admin contact name, use theirs.
FirstName	Optional. Admin user's first name. Ask for it, but proceed without it if the user doesn't provide one.	Optional — leave blank if unsure; only LastName is required for the admin user.
Username	Admin login username. Must be email-format and globally unique across all Salesforce orgs. Max 80 chars. Lowercased on save.	It does not have to be a real inbox — it just has to look like an email and be unique. Suggest a pattern like admin@<company>-<something-unique>.com. If it collides, you'll get a duplicate-username error on create; pick another.
SignupEmail	Admin user's real email address (welcome/login mail goes here).	This one must be a working inbox they can access — unlike Username, it should be a real address.
Company	Company / org name. Max 80 chars.	The organization name to show in the trial org; any descriptive name is fine.
Country	ISO country code, max 3 chars, e.g. US, GB, IN, DE. Validated at runtime against allowed codes (embargoed/invalid codes are rejected).	Use the 2-letter ISO code for their country (e.g. US for United States, GB for United Kingdom). Not a free-text country name.

Exactly one of (required, pick one — NOT both):

Input	Notes	If the user is unsure
TemplateId	Trialforce template ID (key prefix 0TT, 15 chars) — defines the trial org's product/content.	Use a template when they want a specific pre-built product/content set. To find available templates, query the host org: sf data query -o <HOST_ORG> -q "SELECT Id, TemplateName FROM TrialforceTemplate" --json. If they just want a plain trial org, use Edition instead.
Edition	Org edition for a generic (non-template) trial. Generic values: Developer, Group, Professional, Enterprise (also ServiceProfessional, SalesEnterprise). Partner/Trialforce editions are perm-gated.	If they just want "a dev org to try things," use Developer. Partner editions (PARTNER_*, TRIALFORCE_*) only work if the host org has partner/TMC perms — using one without the perm returns a noPartnerAccess error.

Ask the user to choose either a TemplateId or an Edition, not both:

• Neither supplied → stop and ask. A create with no template and no edition fails validation with missingEdition (ApiErrorCodes.INVALID_SIGNUP_OPTION).
• Both supplied → ask them to pick one; send only the chosen field. Combining them fails with redundantTemplateId. Neither may be combined with clone/source-org fields either.

This skill intentionally scopes user-collected input to the fields above (the 5 always-required plus optional FirstName). Do not prompt for or surface other fields. The SignupRequest entity supports additional optional and perm-gated fields (TrialDays, Subdomain, PreferredLanguage, SignupSource, the OAuth-return pair, etc.); these are out of scope here and left to server defaults. They are documented in references/signup_request_fields.md for reference only — do not send them from this skill.

Step 1 — Create the SignupRequest

Invoke the create script with the collected inputs. It enforces the "exactly one of TemplateId/Edition" rule, assembles and quotes the --values payload, runs the insert, and prints the assigned 0SR… id on success. Reference the script by its absolute path from the skill directory (<skill_dir>/scripts/…) — never ./scripts/, which resolves against the user's working directory.

With a template:

SR_ID=$(bash "<skill_dir>/scripts/create_signup_request.sh" \
  --target-org <HOST_ORG> \
  --last-name <LAST_NAME> --email <EMAIL> --username <UNIQUE_USERNAME> \
  --company "<COMPANY>" --country <ISO> --template-id 0TT... \
  --output-dir force-app/main/adk-eval-output)

With an edition (generic trial, no template): replace --template-id 0TT... with --edition Developer (or Enterprise, etc.). Add --first-name <NAME> only if the user supplied it — no other optional fields are sent by this skill. The script rejects supplying both --template-id and --edition, or neither.

Pass --output-dir (use force-app/main/adk-eval-output when it exists) so that if the create is rejected, the script still writes <output-dir>/signup-request-result.json capturing the create-rejected outcome and the raw error verbatim — the run's output artifact even when no org is created. On success this write is done by the Step 2 read-back instead.

On success the script prints the 0SR… SignupRequest id (capture it as SR_ID). Pass --json instead to get the raw sf create envelope, which wraps a handle, not the org:

{ "status": 0, "result": { "id": "0SRxx0000000000", "success": true, "errors": [] } }

Handle create errors (synchronous field validation). On a rejected create the script exits non-zero and prints the raw CLI error (name/code + message) to stderr — surface it verbatim and act per the table below. When --output-dir was given, the script also writes the create-rejected artifact ({ "outcome": "create-rejected", "error": {…}, "CreatedOrgId": null, "Status": null }) to <output-dir>/signup-request-result.json; do not hand-author this file. This is field validation, returned immediately — distinct from the async ErrorCode in Step 2. These are server-side rejections (the record reaches the org and the platform rejects it at insert time) — do not describe them to the user as "client-side"; the CLI does not validate email/country format, picklist values, or field length locally. Do NOT poll a create that failed, and do NOT proceed to Step 2.

Failure	Meaning → what to tell the user
missingEdition / INVALID_SIGNUP_OPTION	Neither TemplateId nor Edition was sent — ask for one and retry.
redundantTemplateId	Both TemplateId and Edition were sent — drop one and retry.
noPartnerAccess / NO_PARTNER_PERMISSION	A partner/TSO edition was requested but the host org lacks the perm — use a generic edition (Developer, etc.) or get the perm.
duplicate / invalid Username (INVALID_EMAIL_ADDRESS)	Username is not email-format or not globally unique — ask for a different one and retry.
INVALID_SIGNUP_COUNTRY	Country is not a valid/allowed ISO code — fix and retry.
INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST	Edition is not an accepted value for the host org's restricted picklist (e.g. Ultimate) — pick a valid generic edition and retry.
STRING_TOO_LONG	A field value exceeds its max length (the message names the field + max length, e.g. LastName over 80) — shorten it and retry.
subdomainInUse / invalid subdomain	Chosen Subdomain is taken or invalid — pick another.
NOT_FOUND ("The requested resource does not exist") or INVALID_TYPE ("sObject type 'SignupRequest' is not supported")	The SignupRequest entity is not exposed → the org is not entitled to create trial orgs. Not retryable. Stop and surface the raw CLI error as-is (name/errorCode + message), then tell the user to reach out to Salesforce support to get the org enabled. Do not name or diagnose the missing permission.
INSUFFICIENT_ACCESS_OR_READONLY	The entity is exposed but the user lacks the access to create the record — a user-permission problem, distinct from the org-entitlement failure above. Fix the user's permissions and retry.

For the full catalog and prefixes → references/error_codes.md.

• For the full required/optional field list, types, and perm-gated fields → load references/signup_request_fields.md.
• Do NOT send TemplateId together with clone/source-org fields (redundantTemplateId error). Do NOT request a partner/Trialforce edition without the host org's partner/TMC perm.

Step 2 — Read the request once the org id is available (creation is async)

Provisioning happens asynchronously after the insert, so re-read the record to pick up the assigned org id. Invoke the read script — it applies a fixed, bounded read-back policy internally (stopping as soon as CreatedOrgId is populated or the status is terminal, and never polling indefinitely), prints the record as JSON, and writes the output artifact when --output-dir is given. Then act on the script's exit code (below) — the retry count and delay are the script's own deterministic logic; you do not re-implement or re-count them in prose. If the org id is not yet available, the script exits 3 so you can hand the request id back to the user:

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" [--output-dir <DIR>]

The script prints the SignupRequest record (the sf envelope's result) as JSON. Read these fields from it:

• CreatedOrgId — the new trial org id (00D…, 15 chars). Populated as soon as the org is allocated (often while Status is still InProgress); this is the script's stop signal.
• CreatedOrgInstance — instance hosting the new org (target follow-up calls here).
• Username — the admin login username on the record. Report the value read back from the record, not the raw input — it is lowercased on save, so the stored value is the accurate one to hand the user.
• Status — lifecycle New → InProgress → Success | Error (match case-insensitively).
• LoginUrl — present only if IsSyncLogin was set on create (perm-gated).
• AuthCode — present only if ConnectedAppConsumerKey + ConnectedAppCallbackUrl were set.
• ErrorCode — populated only when Status = Error. This is the async provisioning error (distinct from the synchronous create-time validation in Step 1), prefixed:
  • C- org creation error · S- signup data error · T- template error (e.g. T-0002 = template not found) · SH- org-shape error · VR- version-selection error · X-0001/X-0002 fatal/should-never-happen.

Act on the script's exit code. The org id lookup runs first — do not report anything to the user until the script returns. Report only what is actually on the record; never invent or relabel the Status:

• 0 — CreatedOrgId is populated. Proceed to Step 3 and report the org id together with the record's real Status and the Username.
• 3 — no org id available yet (not an error). The org has not been allocated. The script has already exhausted its bounded read-back — do NOT re-invoke it in a loop to keep polling. Report the SignupRequest id (0SR…), the record's Status exactly as returned, and the Username; tell the user the org id is not available yet, and let them re-check later (see Step 3).
• 1 — Status = Error (stop and report the ErrorCode and its prefix meaning via references/error_codes.md; the org was not created), or the read itself failed (auth expired, 0SR id not found) — surface the raw CLI error and stop.

Step 3 — Report details and hand off status checks

Report after the Step 2 lookup returns — not before. When the user asks to create (or re-check) the org, run the read-back first and wait for it, then report all available details to the user in one go. Report only what is on the record; never fabricate or relabel a value — especially Status, which must be the exact string the response object carries:

• SignupRequest id — the 0SR… request id (from Step 1). Always report this — it is the handle the user (or a later check) uses to look the request up again, and it is the primary thing to hand back if the org id is not yet available.
• CreatedOrgId — the new trial org id (00D…), when populated. If the read returned exit 3 (org id not yet available), say so plainly: the request was accepted and the org is still being provisioned; there is no org id to share yet.
• CreatedOrgInstance — the instance hosting it, if present.
• Username — the admin login username as stored on the record (lowercased on save). Always report this — it is what the user logs in with once the org is ready.
• Status — the Status value exactly as it appears on the record. Echo whatever string the response carries; do not map, translate, infer, or pick from a fixed list. A still-pending status is normal at this point — provisioning finishes in the background.
• LoginUrl / AuthCode — only if present.

Also tell the user that login details for the new org arrive by email — once provisioning completes, a welcome/login email is sent to the SignupEmail address, so they should watch that inbox to finish logging in. (This is why SignupEmail must be a real, accessible address.)

Then suggest, in plain language, how the user can re-check status later — provisioning may still be completing. Tell them they can just ask (the skill re-reads the record), for example:

• "Check the status of my trial org 00D…" (by the org id), or
• "Check the status of signup request 0SR…" (by the SignupRequest id).

Both resolve to a re-run of the Step 2 read script against the same SignupRequest record (the org id is looked up on that record). A later check should report the current Status exactly as returned on the record. If the record comes back with an error status, also report the ErrorCode and its prefix meaning via references/error_codes.md.

Output artifact. Write the current SignupRequest record as the run's output artifact by passing --output-dir to the Step 2 read script — the script writes <output-dir>/signup-request-result.json (creating the directory if needed). Use force-app/main/adk-eval-output as the output directory when it exists:

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" \
  --output-dir force-app/main/adk-eval-output

This is the run's defined output — do not ask permission before writing it.

Reference File Index

File	When to read
references/signup_request_fields.md	Full field reference — required/optional fields, types, defaults, perm-gated fields, editions
references/error_codes.md	Interpreting ErrorCode prefixes and common validation failures

Example Files

Load these only when you need to see the concrete shape of a payload or response — they are illustrative samples with placeholder ids (0SRxx…, 00Dxx…), not values to send.

File	When to read
examples/create_request.json	When assembling the create — to confirm the field names/shape of the SignupRequest create payload
examples/success_response.json	When interpreting a successful create + read-back — shows the record once CreatedOrgId is populated
examples/error_response.json	When interpreting a rejected create — shows the shape of common validation/error responses