Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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.geminiThe 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

NameDoes
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

NameDoes
uji.http.request(opts, on_done)Sends an HTTP request and returns a function that cancels it.

Files

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
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

NameDoes
uji.diagnostics.list(on_done)Returns the errors uji recorded, newest first.

Quitting and reloading

NameDoes
uji.quit()Exits uji.
uji.reload()Restarts uji on the same session with your config read again.

Runtime

NameDoes
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.osReads the platform, the environment and the clock.
uji.modules(namespace)Lists the modules inside a namespace.
uji.keychainReads and writes secrets in the system keychain.
uji.clipboardReads 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.base64Encodes and decodes base64.
uji.tomlReads 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.