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.

1. 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):

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

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.