Skip to main content

Unomi 3 · Operator experience

Karaf shell commands in Unomi 3

unomi:crud, tenant session context, cache tools, and task commands — operate without leaving SSH.

The Unomi Karaf shell (ssh -p 8102 karaf@localhost, namespace unomi:) has always been the fastest way to inspect rules, tail events, and manage lifecycle. Unomi 3 ( UNOMI-879 / UNOMI-880 / #755 / #763) widens that toolkit for multi-tenancy, caches, and the cluster-aware scheduler — with a unified CRUD surface instead of one-off list/view/remove commands for every type.

Unomi 3 shell: crud, tenant, cache, and task command families

Capabilities at a glance

  • Unified unomi:crud — create / read / update / delete / list / help for many object types
  • JSON or file input — inline JSON, file:// paths, or positional id + body patterns
  • Tabular + CSV lists — ASCII tables with --csv and -n / --max-entries
  • Completers — operation, type, and id completion for faster operator workflows
  • Tenant session — unomi:tenant-get / unomi:tenant-set so following commands run in a tenant (or system)
  • Tenant & API key CRUD — create/list/update tenants and API keys from the shell
  • Cache management — unomi:cache stats, reset, clear, inspect, view, remove, watch, filters by tenant/type, CSV
  • Scheduler ops — unomi:task-list|show|cancel|retry|purge|executor (see task scheduler)
  • Validation assist — unomi:list-invalid-objects for rules/segments/goals/campaigns/scoring with unresolved types
  • Classic live debugging — rule-tail, rule-watch, event-tail, rule-reset-stats
  • Lifecycle — setup, migrate, start, stop, version
  • Definition deploy — deploy-definition / undeploy-definition with bundle/type wildcards
  • Extension types — e.g. JSON Schema via unomi:crud ... schema when the extension is installed

Connect and discover

ssh -p 8102 karaf@localhost
# default user/pass: karaf/karaf  (change etc/users.properties ASAP)

unomi:<TAB>              # list commands
unomi:crud help profile  # type cheat-sheet (also: rule, session, event, tenant, ...)
unomi:version
unomi:cache --stats

Tenant context first

# Create a tenant (hashed keys are stored; plaintext only via create apikey)
unomi:crud create tenant '{"itemId":"acme","name":"Acme Corp"}'
unomi:crud create apikey '{"tenantId":"acme","keyType":"PUBLIC"}'
unomi:crud create apikey '{"tenantId":"acme","keyType":"PRIVATE"}'
# plaintext key is printed once for each create apikey — store it immediately
unomi:crud list tenant

unomi:tenant-set acme
unomi:tenant-get
# subsequent CRUD / cache commands use this tenant

Unified CRUD

# Verbs: create | read | update | delete | list | help
# Bodies are positional JSON or a file:// URL (not --file / -d flags)

unomi:crud help rule
unomi:crud list rule --csv -n 50
unomi:crud read rule my-rule-id

# Rules use metadata for name/enabled (not top-level name/enabled)
unomi:crud create rule file:///tmp/rule.json
unomi:crud create rule '{"itemId":"my-rule-id","metadata":{"id":"my-rule-id","name":"My rule","enabled":true},"condition":{"type":"matchAllCondition","parameterValues":{}},"actions":[]}'
unomi:crud update rule my-rule-id '{"itemId":"my-rule-id","metadata":{"id":"my-rule-id","name":"My rule","enabled":false},"condition":{"type":"matchAllCondition","parameterValues":{}},"actions":[]}'
unomi:crud delete rule my-rule-id

unomi:crud create apikey '{"tenantId":"acme","keyType":"PRIVATE"}'
# plaintext key is printed once — store it immediately

unomi:crud list profile -n 20
unomi:crud list schema          # when json-schema extension is present

Object types registered for unomi:crud

actiontype, apikey, campaign, campaignevent, conditiontype, consent, event, goal, persona, profile, profilealias, propertytype, rule, rulestats, scope, scoring, segment, session, tenant, topic, plus extension types such as schema.

Use unomi:crud help <type> for the property cheat-sheet of that type (required fields, optional maps, common event types).

Profiles, sessions, and events

Day-to-day operator work often means inspecting or patching customer data in a tenant. Set the tenant once, then use the same unomi:crud verbs on profile, session, and event.

Profiles

# Discover shape + recent profiles (sorted by lastUpdated / lastVisit)
unomi:crud help profile
unomi:crud list profile -n 20
unomi:crud list profile --csv -n 50

# Full JSON dump of one profile
unomi:crud read profile PROFILE_ID

# Create (top-level keys become profile properties; itemId is the profile id)
unomi:crud create profile '{"itemId":"demo-ada","firstName":"Ada","lastName":"Lovelace","email":"ada@example.com"}'

# Or from a file
unomi:crud create profile file:///tmp/profile-ada.json

# Update replaces the profile properties map with the JSON you pass
# (include every property you want to keep)
unomi:crud update profile demo-ada '{"firstName":"Ada","lastName":"Lovelace","email":"ada@apache.org","company":"Analytical Engines"}'

# Remove
unomi:crud delete profile demo-ada

There are no separate profile-list / profile-view commands in Unomi 3 — use unomi:crud list|read|delete profile.

Scope first

Sessions and events must reference a scope that already exists for the tenant. Without it, event schema validation logs Unknown scope value and rejects the payload.

# Scope name lives under metadata (not a top-level "name" field)
unomi:crud create scope '{"itemId":"myscope","metadata":{"id":"myscope","name":"My scope"}}'
unomi:crud list scope

Sessions

unomi:crud help session
unomi:crud list session -n 20
unomi:crud read session SESSION_ID

# Create a session bound to a profile (ISO-8601 timestamps)
unomi:crud create session '{"itemId":"demo-session-1","profileId":"demo-ada","scope":"myscope","timeStamp":"2026-07-15T10:00:00Z","properties":{"origin":"shell-demo"}}'

# Update session metadata / properties (full session document)
unomi:crud update session demo-session-1 '{"itemId":"demo-session-1","profileId":"demo-ada","scope":"myscope","timeStamp":"2026-07-15T10:00:00Z","lastEventDate":"2026-07-15T10:05:00Z","properties":{"origin":"shell-demo","channel":"web"}}'

unomi:crud delete session demo-session-1

Required fields for create: itemId, profileId, timeStamp, scope. Use unomi:crud list|read session (the old session-list / session-view commands are gone).

Events

unomi:crud help event
unomi:crud list event -n 50
unomi:crud read event EVENT_ID

# View events: put pageInfo under target.properties (built-in sessionReferrer reads referringURL there)
unomi:crud create event '{"itemId":"demo-event-1","eventType":"view","scope":"myscope","profileId":"demo-ada","sessionId":"demo-session-1","source":{"itemType":"site","scope":"myscope","itemId":"mysite"},"target":{"itemType":"page","scope":"myscope","itemId":"homepage","properties":{"pageInfo":{"pagePath":"/home","pageName":"Home","destinationURL":"https://example.com/home","referringURL":"https://example.com/","language":"en"}}},"persistent":true}'

unomi:crud update event demo-event-1 '{"itemId":"demo-event-1","eventType":"view","scope":"myscope","profileId":"demo-ada","sessionId":"demo-session-1","source":{"itemType":"site","scope":"myscope","itemId":"mysite"},"target":{"itemType":"page","scope":"myscope","itemId":"checkout","properties":{"pageInfo":{"pagePath":"/checkout","pageName":"Checkout","destinationURL":"https://example.com/checkout","referringURL":"https://example.com/home","language":"en"}}},"persistent":true}'

unomi:crud delete event demo-event-1

# Prefer file:// for larger payloads
unomi:crud create event file:///tmp/view-event.json

Common eventType values include view, form, login, identify, modifyConsent, sessionCreated, profileUpdated. For live traffic use unomi:event-tail; for history use unomi:crud list|read event (legacy event-list / event-search were replaced by CRUD).

Typical inspect loop

unomi:tenant-set acme

# Who showed up recently?
unomi:crud list profile -n 10

# Open one profile, then its latest sessions / events
unomi:crud read profile demo-ada
unomi:crud list session -n 10
unomi:crud list event -n 20

# Live: watch events and rule hits while you reproduce in the browser
unomi:event-tail
unomi:rule-tail

Cache

unomi:cache --stats
unomi:cache --stats --detailed --tenant acme
unomi:cache --stats --type profile --csv
unomi:cache --clear --tenant acme
unomi:cache --inspect
unomi:cache --view --id ENTRY_ID --type TYPE --tenant acme
unomi:cache --remove --id ENTRY_ID --type TYPE --tenant acme
unomi:cache --watch 5

Scheduler (shell twin of REST)

unomi:task-list -s RUNNING
unomi:task-list -t profile-purge --limit 20
unomi:task-show TASK_ID
unomi:task-retry TASK_ID --reset
unomi:task-cancel TASK_ID
unomi:task-purge --days 14 --force
unomi:task-executor

Still there: live debugging & lifecycle

Dedicated list/view/remove commands for profiles, sessions, events, rules, segments, actions, and conditions were folded into unomi:crud. What remains as first-class commands:

  • unomi:rule-reset-stats, unomi:rule-tail, unomi:rule-watch RULE_ID…
  • unomi:event-tail (live stream; Ctrl+C to stop)
  • unomi:list-invalid-objects
  • unomi:deploy-definition / unomi:undeploy-definition
  • unomi:setup, unomi:migrate, unomi:start, unomi:stop, unomi:version

Day-to-day inspect/edit for profiles, sessions, events, rules, segments, and the rest goes through unomi:crud; use the tails when you need a live console feed.

Manual: shell commands Task scheduler Multi-tenancy

← All posts