The usual way to query an Oso knowledge base is through the API in your application’s language. But especially during development and debugging, it can be useful to interactively query a policy. So Oso provides a simple REPL (Read, Evaluate, Print, Loop). To run it, first make sure that you have installed Oso.

Once Oso is installed, launch the REPL from the terminal:

There are three ways to start the REPL depending on how you installed Oso.

If you installed Oso globally (with npm install -g oso), you should have an oso executable on your PATH:

$ oso

If you installed Oso into a project and are using Yarn, you can run yarn oso to start the REPL:

$ yarn oso

If you installed Oso into a project and are using NPM, you can add a script to the scripts property of your project’s package.json:

"scripts": {
    "oso": "oso"

With that new script in place, npm run oso will start the REPL:

$ npm run oso

At the query> prompt, type a Polar expression and press Enter. The system responds with an answer, then prints the query> prompt again, allowing an interactive dialog:

query> 1 = 1
query> 1 = 2
query> x = 1 and y = 2
y => 2
x => 1
query> x = 1 or x = 2
x => 1
x => 2
query> x = 1 and x = 2

If the query can not be satisfied with the current knowledge base, the response is false. If the query is unconditionally true, then the response is true. Otherwise, each set of bindings that makes it true is printed; e.g., the third example above has one such set, the fourth has two.

To exit the REPL, type Ctrl-D (EOF).

Loading Policy and Application Code

To query for predicates defined in a policy, we’ll need to load the policy files. For instance, suppose we had just one allow rule for Alice, say, in the file alice.polar:

allow("", "GET", expense: Dictionary) if == 1;

Then we can run the REPL, passing that filename (and any others we need) on the command line:

$ oso alice.polar

And now we can use the rule that was loaded:

query> allow("", "GET", {name: "my expense", id: 1})

We can also use application objects in the REPL, but we have to load and register the defining modules before we launch the REPL. The easiest way to do that is to write a script that imports the necessary modules, plus oso, and then use the Oso.repl() API method to start the REPL:

const { Expense, User } = require('./models');
const { Oso } = require('oso');

const oso = new Oso();
await oso.loadFiles(["alice.polar"])
await oso.repl();

Connect with us on Slack

If you have any questions, or just want to talk something through, jump into Slack. An Oso engineer or one of the thousands of developers in the growing community will be happy to help.