Available APIs
Every function lives under the global uji table. A function that finishes later takes a callback as its last argument, which receives the result, or nil and an error message. Called without the callback from a slash command, a key binding, a timer or a click handler, it waits and returns the result instead. A function that starts background work returns a function that stops it. Wrong arguments raise an error at the call.
Tools
| Name | Does |
|---|---|
uji.tool.add(name, spec) | Registers a tool the model can call, or replaces the tool with the same name. |
uji.tool.display(name, opts) | Describes a tool that uji does not run itself, so the transcript and the approval question can name its calls. |
uji.tool.remove(name) | Removes a tool and returns true if it existed. |
uji.tool.list() | Returns the names of every registered tool. |
uji.tool.disable(names) | Turns tools off. The model still sees them, and uji denies any call to them. |
uji.tool.enable(names) | Turns tools back on after uji.tool.disable. |
uji.tool.policy(rules, opts) | Sets which tool calls run without asking, which ask first, and which uji refuses. |
uji.diff(old, new, path) | Compares two texts line by line and returns the change, for a tool result or an approval preview. |
Commands
| Name | Does |
|---|---|
uji.command.add(name, spec) | Registers /name, or replaces the command with the same name, built-in or not. |
uji.command.remove(name) | Removes a command and returns true if it existed. |
uji.command.list() | Returns the names of every command in alphabetical order. |
Keys
| Name | Does |
|---|---|
uji.keymap.add(mode, key, binding) | Binds a key in one mode, replacing what the key did there. |
uji.keymap.remove(mode, key) | Unbinds a key in one mode, including a default binding. |
uji.keymap.reset() | Restores the default bindings. |
uji.keymap.list() | Returns one row per binding, with mode, key, and one of action, command or unbound = true. |
Actions
| Name | Does |
|---|---|
uji.action.add(name, handler) | Registers an action. |
uji.action.remove(name) | Removes an action you added and returns true if it existed. |
uji.action.list() | Returns the names of every action, built-in and added, in alphabetical order. |
Windows, pickers and appearance
| Name | Does |
|---|---|
uji.ui.toolbar(items) | Declares toolbar items on the screen and returns a handle that removes them. |
uji.ui.status(content) | Draws a view as the status line and returns a handle that puts the built-in line back. |
uji.ui.size() | Returns the width and height of the terminal. |
uji.ui.select(opts, on_done) | Shows a list to choose from. |
uji.ui.pick(opts, on_done) | Shows a fuzzy finder with a preview pane. |
uji.ui.prompt(opts, on_done) | Asks for a line of text. |
uji.ui.confirm(opts, on_done) | Asks a yes or no question, including uji’s approval questions. |
uji.ui.overlay(content, opts) | Shows a view in a box over the screen until you close it. |
uji.ui.Markdown(text) | A view that draws markdown. |
uji.ui.toggle_thinking() | Shows or hides the model’s reasoning in the transcript. |
uji.ui.exec(cmd) | Hides uji, runs a program in the terminal, and comes back when it exits. |
uji.ui.open(target) | Opens a file or link in the app the system uses for it. |
uji.ui.configure(opts) | Sets colours and screen behaviour. |
uji.ui.theme() | Returns the theme in use. |
uji.ui.save_theme(name) | Keeps a theme for the next time uji starts. |
Model context
| Name | Does |
|---|---|
uji.context.add(name, provide, opts) | Registers a function that uji calls at the start of every turn. |
uji.context.remove(name) | Removes a context function and returns true if it existed. |
uji.context.list() | Returns the names of the context functions, in the order uji calls them. |
uji.context.configure(opts) | Sets how long the provider caches the conversation, and when uji compacts. |
Events
| Name | Does |
|---|---|
uji.on(event, handler, opts) | Adds a handler for an event and returns the handler’s name. |
uji.off(event, name) | Removes the handler with that name and returns true if it existed. |
uji.emit(event, payload) | Runs the handlers of any event with the payload you give. |
Session
| Name | Does |
|---|---|
uji.session.info() | Returns a table with the session’s id, title, directory and short_directory. |
uji.session.messages() | Returns the transcript as a list of tables with type and text. |
uji.session.usage() | Returns the tokens spent in this session. |
uji.session.context() | Returns a table with used, the estimated tokens in the conversation, and window, the model’s context size when uji knows it. |
uji.session.queue() | Returns the messages you typed while the model worked, which uji has not sent yet. |
uji.session.state() | Returns "working" while a turn runs and "idle" otherwise. |
uji.session.elapsed() | Returns the seconds since the current turn started, or nil when idle. |
uji.session.set_title(title) | Renames the session, saves the name, and fires session_titled. |
uji.session.submit(text) | Sends a message as if you typed it. |
uji.session.interrupt() | Stops the current turn, or the running ! command. |
uji.session.compact() | Summarises earlier messages to free context. |
uji.session.resume(id) | Starts uji again in the session the id names. |
Input line
| Name | Does |
|---|---|
uji.input.get() | Returns the text on the input line. |
uji.input.set(text) | Replaces the text on the input line. |
uji.input.append(text) | Adds text to the end of the input line. |
uji.input.clear() | Empties the input line. |
uji.input.attach(path) | Attaches an image file to the message on the input line. |
uji.input.capture(handler) | Sends every key press to handler instead of the normal bindings, until uji.input.release runs. |
uji.input.release() | Returns the keyboard to the normal bindings. |
Models
| Name | Does |
|---|---|
uji.model.current() | Returns the provider, model, API root and effort the next turn uses. |
uji.model.use(opts) | Changes the provider, model, API root or effort, and saves the choice. |
uji.model.efforts() | Returns the reasoning efforts the current model accepts. |
uji.model.decide(opts) | Asks a provider how likely it is that each question about a state is yes. |
Providers
| Name | Does |
|---|---|
uji.provider.add(spec) | Adds a provider, or merges spec into the provider with the same id. |
uji.provider.remove(id) | Removes a provider and returns true if it existed. |
uji.provider.list() | Returns one table per provider with its settings and models. |
uji.auth.configure(opts) | Chooses between auth.toml and the system keychain for API keys and sign-ins. |
uji.auth.authenticated(id) | Returns true when uji has a key or sign-in for a provider. |
uji.auth.save_key(id, key) | Saves an API key for a provider. |
uji.auth.login(id, opts, on_done) | Signs in to a provider in the browser or with a device code. |
Provider APIs
| Name | Does |
|---|---|
uji.class(parent) | Makes a class, optionally from a parent class whose methods it keeps. |
uji.api.openai, uji.api.responses, uji.api.anthropic, uji.api.gemini | The API classes a provider’s api is made from. |
uji.api.stream.run(spec, reply) | Sends a request to a streaming endpoint and reads the events into an answer. |
Processes
| Name | Does |
|---|---|
uji.job.start(opts) | Starts a process and returns a job table. |
uji.jobs.list() | Returns the background jobs. |
uji.jobs.stop(id) | Stops a running background job. |
uji.jobs.show() | Opens the jobs list under the input, running ones first. |
uji.jobs.configure(opts) | Sets whether a finished job wakes the model, how many jobs run at once, and how long they may run. |
HTTP
| Name | Does |
|---|---|
uji.http.request(opts, on_done) | Sends an HTTP request and returns a function that cancels it. |
Files
| Name | Does |
|---|---|
uji.fs.read(path, on_done) | Reads a whole file. |
uji.fs.lines(path, opts, on_done) | Reads a range of lines from a text file. |
uji.fs.write(path, content, on_done) | Writes a file, creating missing directories. |
uji.fs.list(path, on_done) | Lists a directory. |
uji.fs.glob(pattern, on_done) | Lists the paths that match a pattern. |
uji.fs.join(base, ...) | Joins parts into one path. |
uji.data.read(name, on_done) | Reads a plugin’s file in the data directory. |
uji.data.write(name, text, on_done) | Writes a plugin’s file in the data directory. |
uji.config.files(folder, opts, on_done) | Reads the files in a folder of your config, your packs and, if asked, the project. |
JSON
| Name | Does |
|---|---|
uji.json.encode(value) | Turns a Lua value into a JSON string. |
uji.json.decode(text, opts) | Turns a JSON string into a Lua value. |
uji.json.array(table) | Marks a table as a JSON array, so it encodes as [] even when empty. |
Packs
| Name | Does |
|---|---|
uji.pack.add(specs) | Installs and loads packs. |
uji.pack.list() | Returns every directory uji searches for modules and plugin/ files, starting with your config directory. |
uji.pack.update() | Pulls every installed git pack and records the new commits in the lock file. |
Timers and notices
| Name | Does |
|---|---|
uji.schedule(callback) | Runs callback once the code that called it has finished. |
uji.defer(seconds, callback) | Runs callback after a delay and returns a function that cancels it. |
uji.notify(message, seconds) | Shows a notice at the top right of the screen, seconds by default the theme’s limits.flash. |
Diagnostics
| Name | Does |
|---|---|
uji.diagnostics.list(on_done) | Returns the errors uji recorded, newest first. |
Quitting and reloading
| Name | Does |
|---|---|
uji.quit() | Exits uji. |
uji.reload() | Restarts uji on the same session with your config read again. |
Runtime
| Name | Does |
|---|---|
uji.task.spawn(fn, ...) | Starts a function as a task that runs alongside the rest of uji. |
uji.sleep(seconds) | Pauses the current task. |
uji.task.race(fn, ...) | Runs functions at once and returns the first to finish. |
uji.task.timeout(seconds, fn) | Runs a function with a time limit. |
uji.promise() | Returns a promise that tasks can wait on. |
uji.net.request(opts) | Sends an HTTP request and returns the answer. |
uji.net.open(opts) | Sends an HTTP request and streams the answer. |
uji.net.listen(port) | Accepts connections on a local port. |
uji.proc.spawn(argv, opts) | Starts a process. |
uji.db.open(path) | Opens a SQLite database. |
uji.os | Reads the platform, the environment and the clock. |
uji.modules(namespace) | Lists the modules inside a namespace. |
uji.keychain | Reads and writes secrets in the system keychain. |
uji.clipboard | Reads and writes the system clipboard, and reads images from it. |
uji.regex(pattern) | Compiles a regular expression. |
uji.glob(pattern, opts) | Compiles a glob. |
uji.fuzzy(query, items) | Ranks strings against a query. |
uji.markdown(source) | Parses Markdown into events. |
uji.width(text) | Measures text in terminal columns. |
uji.lossy(data) | Turns bytes into valid UTF-8. |
uji.base64 | Encodes and decodes base64. |
uji.toml | Reads and writes TOML. |
uji.sha256(data) | Hashes data. |
uji.random(count) | Returns random bytes. |
uji.image.fit(data, edge, bytes) | Checks an image and fits it to a size and a byte limit. |