How to Look Up OpenResty Documentation in Your Terminal with restydoc

Check out how OpenResty XRay helps organizations troubleshoot issues and optimize the performance of their applications.

Learn More LIVE DEMO

restydoc is OpenResty’s built-in command-line utility for looking up OpenResty documentation without opening a browser. Modeled after Perl’s perldoc, it gives you instant access to Nginx directive references, the OpenResty Lua API, LuaJIT extensions, and bundled Lua module docs — all from your terminal. It ships with OpenResty itself, so no separate installation is required. If you are new to OpenResty’s CLI tools, see also the resty command for running Lua scripts interactively.

This tutorial demonstrates how to use OpenResty’s restydoc command-line utility to quickly lookup OpenResty documentation for Nginx modules, Nginx configuration directives, Lua API functions, Lua C functions, Lua modules, and many more. The restydoc tool was originally inspired by Perl’s perldoc utility.

Install and Locate restydoc

which restydoc
rpm -qf `which restydoc`

The restydoc utility is shipped with OpenResty itself. The package name is openresty-doc on Yum-based systems.

The package name is openresty-restydoc on Debian-based systems, like Ubuntu 20.04.

ssh ubuntu20-pkg

which restydoc
dpkg -S `which restydoc`

Look Up Nginx Configuration Directives

We can lookup the docs for the standard Nginx directive rewrite like this.

restydoc -s rewrite

Note the -s option, which means “section”.

It is extracted from the official Nginx documentation. Under the hood, it invokes the less utility.

We can use the space key to switch to the next page.

We use the q key to quit.

Or the standard Nginx’s listen directive.

restydoc -s listen

Or our OpenResty’s nginx module directives like init_worker_by_lua.

restydoc -s init_worker_by_lua

Browse the OpenResty Lua API and Lua Functions

Standard Lua functions can be looked up too.

restydoc -s string.find

It is extracted from the official Lua 5.1 reference manual.

Or the standard Lua’s C API functions.

restydoc -s lua_gc

Or the LuaJIT’s Lua API extension.

restydoc -s ffi.cdef

Or OpenResty’s own Lua API extension.

restydoc -s ngx.re.match

All the restydoc commands above specify the -s option. This is because the displayed docs are all sections from some larger documents.

View Full Module Documentation

We can view large documents like a whole Nginx module’s.

restydoc ngx_http_rewrite_module

Here we do not specify the -s option.

It’s much longer, as expected.

Or a whole Lua module.

restydoc resty.redis

This is the resty.redis library shipped with OpenResty.

Or specifying the Lua library name.

restydoc lua-resty-lrucache

restydoc Command Options

To view all the options of restydoc, use the -h option.

restydoc -h

That’s all I’d like to cover today. Hopefully you’ve found this tool useful.

Frequently Asked Questions

What is restydoc in OpenResty? restydoc is a command-line tool bundled with OpenResty for browsing OpenResty documentation directly in your terminal. It covers Nginx directives, the OpenResty Lua API, LuaJIT extensions, and bundled Lua module docs. Modeled after Perl’s perldoc, it opens the relevant docs in the less pager — no browser required.

How do I install restydoc? restydoc ships with the OpenResty distribution and requires no separate installation. On RPM-based systems (RHEL, CentOS, Fedora), it is included in the openresty-doc package. On Debian-based systems such as Ubuntu, the package is named openresty-restydoc.

Can restydoc show OpenResty Lua API documentation? Yes. Use restydoc -s ngx.re.match for OpenResty’s ngx.* Lua API, restydoc -s string.find for standard Lua functions, restydoc -s ffi.cdef for LuaJIT FFI extensions, and restydoc -s lua_gc for the Lua C API. The -s flag selects a specific section within a larger reference document.

What types of documentation does restydoc cover? restydoc covers four main areas: standard Nginx configuration directives (such as rewrite and listen), OpenResty-specific Nginx module directives (such as init_worker_by_lua), Lua and LuaJIT API references, and complete Lua module documentation for libraries like resty.redis and lua-resty-lrucache.

Continue the OpenResty Tutorial Series

Return to the OpenResty Tutorial Series overview.

If you like this tutorial, please subscribe to this blog site and our YouTube channel. Thank you!

About The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty^® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty^®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.