j17 - Event sourcing for the rest of us

An instance contains three isolated environments: test, staging, and prod. The CLI saves one instance/environment pair as your current context, while still allowing explicit overrides for individual commands.

List instances

j17 instance list

The table includes each instance's name, ID, tier, and status. For structured output:

j17 instance list --json

Create an instance

j17 instance create my-app
j17 instance create my-app --tier hobby

The default tier is free. Supported user-facing tier values are free, hobby, and pro.

Creating an instance does not select it automatically. Use j17 use after creation.

Show an instance

Names and UUIDs are both accepted:

j17 instance show my-app
j17 instance show 550e8400-e29b-41d4-a716-446655440000

Update an instance

Change the name, tier, or both. The instance in the first argument is resolved before a rename, so it may be either the current name or UUID:

j17 instance update my-app --tier alpha
j17 instance update my-app --name customer-api
j17 instance update my-app --name customer-api --tier pro

At least one of --name or --tier is required. The server checks whether the tier is active and available to your account; the CLI deliberately does not keep its own list of plans. Updating an instance requires owner or administrator access.

Select a working context

j17 use my-app --env test

j17 use verifies that you can access the instance, then stores both its immutable ID and its display name with the environment. Subsequent API-key and spec commands address the saved instance by ID, so renaming it—or later reusing its old name—cannot redirect those commands. The environment is required and must be test, staging, or prod.

The saved selection is used by API-key and spec commands:

j17 key list
j17 spec deploy

Override the selection

Use --instance and --env when a command should not use the saved context:

j17 key list --instance another-app --env staging
j17 spec deploy ./specs/next.json --instance another-app --env test

Explicit flags take precedence over the saved profile. The override applies only to that invocation and does not change the selection saved by j17 use.

Commands that mutate an environment, such as key create and spec deploy, refuse to guess an environment. They require either a saved environment or an explicit --env; they never silently choose production.

Profiles have separate selections

Each J17_PROFILE stores its own current context:

J17_PROFILE=work j17 use billing --env prod
J17_PROFILE=local j17 use sandbox --env test

This is useful when the same machine works with multiple accounts or control planes. See Login and Credentials.