Quickstart

This quickstart uses the orishare CLI. The CLI is a workspace package of the Orishare repository (packages/cli, built with pnpm --filter @orishare/cli build); it is not published to npm. Without the repository, every step is one HTTP call on https://api.orishare.com, named under each step. Every command prints JSON with --json and exits with a fixed code: 0 ok, 1 API error, 2 usage, 3 authentication, 4 not found, 5 network.

1. Sign up

orishare --json signup --email [email protected] --org "Acme Audiobooks" --timezone America/New_York --save

--save stores the first personal access token in ~/.config/orishare/config.json (mode 0600) with the new test environment as the default. The response lists both environments, one test (runtime_class: sandbox) and one production (kind: live, runtime_class: production); note the test id. Over HTTP: POST /v1/auth/signup.

Until you sign in once at the dashboard with that email (magic link or Google), the production environment holds your direct configuration writes like an agent's: they answer 403 confirmation_required with details.reason email_unverified. This quickstart uses the test environment, which is not affected.

An AI agent with no browser and no person signs up differently: two HTTP calls with a proof of work, no email at all. See Start here for AI agents.

2. Create a secret key for your server

orishare --json keys create --environment env_… --name backend
export ORISHARE_TOKEN=osk_test_…   # printed once

Flags beat environment variables, which beat the profile: --token, ORISHARE_TOKEN, then the saved profile. Over HTTP: POST /v1/environments/{id}/api_keys with { "kind": "secret", "name": "backend" }, a PAT and an Idempotency-Key; the key gets the default scopes listed in the agent guide.

3. Publish a rule

Save this as purchase.json:

{
  "schema": "orishare.rule/v1",
  "trigger": { "event": "content.purchased" },
  "limits": [
    { "id": "per_content", "scope": ["customer", "event.properties.content_id"], "max": 1 }
  ],
  "actions": [{ "type": "points.award", "currency": "points", "amount": 100 }]
}

orishare --json rules create --file purchase.json --name purchase --publish
orishare --json rules simulate rule_… --event content.purchased --property content_id=book_1

Simulation runs the real engine against a synthetic event and writes nothing. Over HTTP: POST /v1/rules, then POST /v1/rules/{id}/publish with If-Match, and POST /v1/rules/{id}/simulate.

Or let the model draft it and review the result before anything is created:

orishare --json ai draft "Give 100 points the first time a customer buys a title"

Drafts are validated against your observed events, currencies and rewards; see AI drafting.

4. Send an event and read the state

orishare --json events send --name content.purchased --customer alice --property content_id=book_1 --sync
orishare --json customers state alice

The sync response carries effects (points.awarded, 100) and a trace naming the rule and its outcome. customers state shows balances, tiers, segments, counters, challenges and issuances. Over HTTP: POST /v1/events with mode: "sync" and customer_id: "alice" (your external id), then GET /v1/customers/{id}/state with alice as the id (it accepts the external id too). Send the same purchase again and the trace reports the per_content limit as exhausted.

5. Everything else

orishare api <method> <path> reaches any route in the API reference, for example orishare api get /rewards or orishare api post /webhook_endpoints --data @endpoint.json. Use orishare config pull --schema v2 > test.json and orishare --env env_live… config push --file test.json to preview a promotion to the production environment, then apply as Promote between environments shows.