Skip to content
xs

Working with Contexts

Cross.stream uses contexts to partition event streams. Every frame belongs to a context, with the system context being the default where operations happen if no specific context is specified.

System Context

When you first start using cross.stream, you’re working in the system context. The system context contains the initial xs.start frame and any other frames you create without specifying a different context.

Terminal window
.cat
─#─┬──topic───┬────────────id─────────────┬─hash─┬─meta─┬───ttl───
 0 │ xs.start │ 03d4q1o70y6ek0ig8hwy9q00n │      │      │
───┴──────────┴───────────────────────────┴──────┴──────┴─────────

Creating Contexts

Create a new named context using the .ctx new command:

Terminal window
.ctx new my-project
03d4qbrxizqgav09m7hicksb0

This creates a context named “my-project” and automatically switches to it.

Listing Contexts

View all available contexts:

Terminal window
.ctx list
─#─┬───────────────id───────────────┬───name─────┬─active──
 0 │ 0000000000000000000000000      │ system     │ true
 1 │ 03d4qbrxizqgav09m7hicksb0      │ my-project │ false
───┴────────────────────────────────┴────────────┴─────────

You can also use the .ctx ls alias for the same output.

Switching Contexts

Switch between contexts using either their names or IDs:

Terminal window
.ctx switch my-project
03d4qbrxizqgav09m7hicksb0
> .ctx switch 03d4qbrxizqgav09m7hicksb0
03d4qbrxizqgav09m7hicksb0

You can also switch interactively by running .ctx switch without arguments.

Renaming Contexts

You can rename contexts using the context ID:

Terminal window
.ctx rename 03d4qbrxizqgav09m7hicksb0 feature-work

This updates the name associated with the specified context ID.

Using Contexts

Once you’ve switched to a context, all operations happen in that context:

Terminal window
"project note" | .append notes
.cat
─#─┬──topic───┬────────────id─────────────┬────────────────────────hash─────────────────────────┬─meta─┬───ttl───
 0 │ notes    │ 03d4qbrxizqgav09m7hicksb0 │ sha256-KDyb7pypM+8aLiq5obfpCqbMmb6LvvPnCu2+y9eWd0c= │      │ forever
───┴──────────┴───────────────────────────┴─────────────────────────────────────────────────────┴──────┴─────────

You can explicitly specify a context with any command using the -c parameter:

Terminal window
"new feature idea" | .append notes -c feature-branch
.cat -c feature-branch
─#─┬──topic───┬────────────id─────────────┬────────────────────────hash─────────────────────────┬─meta─┬───ttl───
 0 │ notes    │ 03f8q6rxnzqgav09n7hicksb9 │ sha256-LMcRiyKpOjA1Z8O+wZvoiMXYgGEzPQOhlA8AOptOhBY= │      │ forever
───┴──────────┴───────────────────────────┴─────────────────────────────────────────────────────┴──────┴─────────

The head command is also context-aware:

Terminal window
.head notes -c feature-branch | .cas
new feature idea

Viewing Current Context

See the ID of your current context:

Terminal window
.ctx
03d4qbrxizqgav09m7hicksb0

Viewing All Contexts

View frames across all contexts with the --all flag:

Terminal window
.cat --all
─#─┬──topic───┬────────────id─────────────┬────────────────────────hash─────────────────────────┬─meta─┬───ttl───
 0 │ xs.start │ 03d4q1o70y6ek0ig8hwy9q00n │                                                     │      │
 1 │ notes    │ 03d4qbrxizqgav09m7hicksb0 │ sha256-KDyb7pypM+8aLiq5obfpCqbMmb6LvvPnCu2+y9eWd0c= │      │ forever
 2 │ notes    │ 03f8q6rxnzqgav09n7hicksb9 │ sha256-LMcRiyKpOjA1Z8O+wZvoiMXYgGEzPQOhlA8AOptOhBY= │      │ forever
───┴──────────┴───────────────────────────┴─────────────────────────────────────────────────────┴──────┴─────────