NOOSChain Operator Recipes

Operator recipes are guided CLI workflows for common operational tasks. They sit on top of lower-level commands such as noos tx build and do not bypass consensus execution.

Use recipes when you want the CLI to explain the task, validate the input, and show safe next steps.

Safety Model

• Initialization recipes build signed consensus transactions.
• Recipes submit only when --yes is provided.
• Without --yes, recipes build a transaction and either print it or write it to --output.
• --dry-run validates payload JSON, signer identity, and nonce lookup without writing a transaction file or submitting to the node.
• Organization and user registration are transaction-only. There are no direct table mutation commands.
• Bucket changes are transaction-only. Recipes use /transactions for submission.

Recipes need the same environment as noos tx build:

$env:DATABASE_URL = "postgres://..."
$env:NOOS_CLI_BASE_URL = "http://127.0.0.1:3000"
$env:NOOS_OPERATOR_TOKEN = "..."

The CLI also loads .env from the current working directory.

Listing Recipes

npm run noos -- recipe list

This shows available recipes and editable payload templates.

Payload Templates

Templates are starter JSON files. They are intentionally explicit so operators can review every field before signing.

npm run noos -- recipe init:template organization --output org.json
npm run noos -- recipe init:template user --output user.json
npm run noos -- recipe init:template bucket --output bucket.json
npm run noos -- recipe init:template bucket-policy --output policy.json
npm run noos -- recipe init:template bucket-access-rule --output rule.json

Available templates:

• organization
• user
• bucket
• bucket-policy
• bucket-access-rule

Create An Organization

Generate and edit the template:

npm run noos -- recipe init:template organization --output org.json

Dry-run the transaction:

npm run noos -- recipe init:create-organization `
  --payload-file org.json `
  --signer-public-key="<admin-public-key>" `
  --signer-private-key-path admin.key `
  --dry-run

Build a signed transaction file:

npm run noos -- recipe init:create-organization `
  --payload-file org.json `
  --signer-public-key="<admin-public-key>" `
  --signer-private-key-path admin.key `
  --output org-tx.json

Submit directly:

npm run noos -- recipe init:create-organization `
  --payload-file org.json `
  --signer-public-key="<admin-public-key>" `
  --signer-private-key-path admin.key `
  --yes

Follow-up checks:

npm run noos -- organizations show <organizationId>
npm run noos -- chain verify

Create A User

npm run noos -- recipe init:template user --output user.json

The organizationId must already exist. The publicKey is the user's signing public key.

npm run noos -- recipe init:create-user `
  --payload-file user.json `
  --signer-public-key="<admin-public-key>" `
  --signer-private-key-path admin.key `
  --dry-run

Submit:

npm run noos -- recipe init:create-user `
  --payload-file user.json `
  --signer-public-key="<admin-public-key>" `
  --signer-private-key-path admin.key `
  --yes

Follow-up checks:

npm run noos -- users show <userId>
npm run noos -- organizations users <organizationId>

Create A Bucket

npm run noos -- recipe init:template bucket --output bucket.json

Review these fields carefully:

• replicationPolicy: controls where encrypted payload bytes may be replicated.
• encryptionMode: chooses per-record or per-bucket key material.
• indexSchema: declares public indexes for records in the bucket.
• createdByUserId / createdByOrganizationId: must match real identities.

npm run noos -- recipe init:create-bucket `
  --payload-file bucket.json `
  --signer-public-key="<writer-public-key>" `
  --signer-private-key-path writer.key `
  --dry-run

Submit:

npm run noos -- recipe init:create-bucket `
  --payload-file bucket.json `
  --signer-public-key="<writer-public-key>" `
  --signer-private-key-path writer.key `
  --yes

Follow-up checks:

npm run noos -- observability buckets
npm run noos -- chain verify

Modify Bucket Policy

npm run noos -- recipe init:template bucket-policy --output policy.json

This builds an UPDATE_BUCKET_POLICY transaction. Policy changes affect future records. Historical local ciphertext is not automatically deleted.

npm run noos -- recipe init:update-bucket-policy `
  --payload-file policy.json `
  --signer-public-key="<bucket-admin-public-key>" `
  --signer-private-key-path bucket-admin.key `
  --yes

Follow-up checks:

npm run noos -- observability buckets
npm run noos -- node payloads

Assign A Principal To A Bucket

npm run noos -- recipe init:template bucket-access-rule --output rule.json

The rule can target a user or an organization.

Common permissions:

• bucket:read_metadata: principal can see bucket/record metadata.
• bucket:read_encrypted: principal can receive encrypted payload bytes when policy allows it.
• bucket:write: principal can add records.
• bucket:admin: principal can manage bucket access rules.

npm run noos -- recipe init:assign-bucket-principal `
  --payload-file rule.json `
  --signer-public-key="<bucket-admin-public-key>" `
  --signer-private-key-path bucket-admin.key `
  --dry-run

Submit:

npm run noos -- recipe init:assign-bucket-principal `
  --payload-file rule.json `
  --signer-public-key="<bucket-admin-public-key>" `
  --signer-private-key-path bucket-admin.key `
  --yes

Follow-up checks:

npm run noos -- observability bucket-access-rules
npm run noos -- chain verify

Explaining A Recipe

Every recipe supports --explain:

npm run noos -- recipe init:create-bucket --explain

This prints what the recipe changes, what it requires, and what to check after running it.

Relationship To noos tx

Recipes are convenience wrappers. The lower-level equivalent is:

npm run noos -- tx build --type CREATE_BUCKET --payload-file bucket.json --signer-public-key="<key>" --signer-private-key-path signer.key --output tx.json
npm run noos -- tx submit --file tx.json --yes

Use noos tx when you need full control over transaction type and payload. Use noos recipe when you want a safer guided flow.