j17 - Event sourcing for the rest of us

The CLI can perform a quick local JSON check and deploy a spec through the authenticated control plane.

Spec file shape

j17 spec deploy reads the spec object itself. The CLI adds the HTTP request's outer "spec" field for you, so do not wrap the file in a second "spec" object.

{
  "aggregate_types": {
    "order": {
      "events": {
        "was_placed": {
          "schema": {
            "type": "object",
            "properties": {
              "total": { "type": "number" }
            },
            "required": ["total"]
          },
          "handler": [
            { "set": { "target": "", "value": "$.data" } }
          ]
        }
      }
    }
  },
  "agent_types": ["user"]
}

By default, both spec commands read ./j17.spec.json. Pass a path to use another file.

Local validation

j17 spec validate
j17 spec validate ./specs/app.json

Local validation checks only that the file exists and contains valid JSON. It does not validate the j17 spec grammar, handlers, schemas, or compatibility with an already deployed spec. A successful local check is useful for a fast syntax failure, but it does not guarantee deployment will succeed.

Full semantic and compatibility validation runs on the server during spec deploy.

Deploy

j17 use my-app --env test
j17 spec deploy

Or provide the target explicitly:

j17 spec deploy ./specs/app.json --instance my-app --env staging

The command reports the deployed spec hash and any server warnings. With --json, the response includes the instance, spec_hash, and warnings when present.

Production confirmation

A production deployment prompts before making the request:

Deploy j17.spec.json to instance my-app (env=prod)? [y/N]

For reviewed, non-interactive deployment pipelines, acknowledge that step with --yes:

j17 spec deploy --instance my-app --env prod --yes

Incompatible changes

The server rejects incompatible changes by default.

--force waives the broad backward-compatibility check on test and staging. The CLI refuses --force on production.
--confirm-breaking acknowledges the narrower class of changes that alter how already-stored events are interpreted. It is available in every environment, including production.

j17 spec deploy ./specs/next.json --env test --force
j17 spec deploy ./specs/next.json --env prod --confirm-breaking --yes

These flags answer different questions; one does not imply the other. Review the server's validation error before using either. See Schema Deployment and The Spec for the underlying rules.

Projections