Use Alive with a coding agent

This is the customer entry guide, distinct from contributor AGENTS.md. Use a supplied client artifact; packages are not yet published to PyPI/npm. The Python CLI needs Python 3.13 and the matching alive-cli, alive-sdk and alive-core distributions. A Python SDK-only install is a thin API client and has no local runner. Installing a package does not automatically register instructions with your IDE agent. Ask the agent to read this guide explicitly.

1. Discover before acting

alive doctor --json
alive docs agents
alive world list --json
alive models list --json
alive models show alive.process.referral@1.0.0

doctor reports versions/resources and whether credentials are present; no network call happens unless --remote is given. models show includes ports, units, defaults, constraints and the model card. docs list / docs show reference/world-spec.md open smaller bundled guides. alive schema worldspec prints the current schema without needing repository files.

Keep the question, model assumptions and user-authorized scope explicit. Current models are L1. MCP, browser CLI sign-in, staging connections and Multiverse are planned; decorative homepage terminal calls are not supported interfaces. Do not invent commands from the illustration.

2. Choose the right path

For an idea, use alive init and alive prompt intake, then review an IntakeSpec and run alive intake validate intakespec.json --json and alive plan intakespec.json --json. A concept-only plan need not have a world. Hosted normalization/review requires an account, explicit external-processing approval and any required budget/scope approval.

For a supported synthetic workflow, start with a bundled reference world:

alive world pull rural-clinic --output world.json
alive world validate world.json --json

Pulling is offline and refuses to overwrite unless --force is supplied. Inspect the JSON, especially provenance, variant effects and limitations; the sample is not a test of your actual application. Validation checks references, ports, units and supported model grades, not predictive validity. Fix the paths in error details rather than guessing parameter names.

3. Execute locally or connect explicitly

Local first-party runs need no account:

alive run --world world.json --output evaluation.zip --json

This uses your CPU and writes an archive. It does not exercise a connected product or hosted inference. Do not imply that local execution is a sandbox for arbitrary user code/plugins. Read README.md, AGENTS.md, evaluation/limitations.md and manifest.json in the archive.

For hosted runs, supply a scoped token with ALIVE_TOKEN and a configured ALIVE_API_URL, or use alive login --api-url … --token …. alive whoami --json checks identity/organizations. This is token persistence, not browser login or automatic renewal. logout forgets the saved credential; revoke the token in the app to invalidate it. Customers do not configure Supabase.

Use the SDK to save a reviewed world into a permitted project, or the app world builder, then:

alive runs estimate WORLD_REVISION_ID --json

Stop and obtain the user's approved credit budget. Only then submit:

alive run --remote --world-revision WORLD_REVISION_ID --budget APPROVED_CREDITS \
  --idempotency-key UNIQUE_OPERATION_KEY --json

Replace uppercase placeholders; keep the revision, body and key unchanged for an ambiguous retry. --remote --world world.json --project PROJECT_ID also saves and queues explicitly; if submission fails its structured error includes the saved revision and retry command. Never retry that save path blindly with a new key. Authentication is not approval to spend or upload source material.

4. Resume and inspect

alive runs get RUN_ID --json
alive results get RUN_ID --json
alive events list RUN_ID --limit 100 --offset 0 --json
alive experiments compare RUN_ID --json
alive results export RUN_ID --output evaluation.zip --json

Poll status at a reasonable interval; inspect results after succeeded or timed_out. Begin with findings, assumptions and metrics before retrieving events. Follow next_offset explicitly; events_included reports trace retention. The export refuses to replace an existing destination. Compare alternatives as paired variants of one world, not arbitrary independent runs. To change an assumption, create a reviewed variant and repeat validation/estimate/approval. Typed findings distinguish observed technical failures from conditional outcomes and AI hypotheses.

Cancellation is available with alive runs cancel RUN_ID. An already-running calculation may finish and settle through the existing worker path; forceful interruption is not implemented.

5. Recover with identity intact

--json keeps success/error data on stdout and progress on stderr. An error has an error object with code, message, details, request_id and idempotency_key; remote run failures also carry the saved revision/retry command when applicable. Exit codes: 0 success, 1 invalid document, 2 usage/filesystem error, 3 API/network/protocol error, 4 input or approval needed. Help remains normal command help.

alive author sessions never wait on stdin when output is not a terminal or --json/--no-input is set: they print the checkpoint (questions with ids) and exit 4. Relay the questions to the person, then continue with alive author answer <session> --set <question_id>=<answer> --relayed. Never answer on the person's behalf; --relayed records that an agent passed their answer on.

For expired auth, reconnect; for malformed worlds, fix indicated paths; for quota/budget failure, review the estimate/approval; for an interrupted request, retain the key and run/revision id. Do not start duplicate billable work. See errors and limits, Python SDK and CLI reference.

The website also supplies plain Markdown and a versioned discovery index at /llms.txt and /developers/discovery.json. These help discovery; they do not execute tools or guarantee that any agent automatically loads instructions. Clean-install IDE acceptance remains a release gate.