In this tutorial, we will demonstrate how to use the RESTY command-line tools that come with OpenRESTy.

cd ~
export PATH=/usr/local/openresty/bin:$PATH
which resty

It’s always going to be this path.

We can check the version number with the -v option.

resty -V

If you install OpenResty using our pre-built Linux binary package, then you should install the OpenResty-Resty package.

dnf list installed openresty-resty

Because it’s not in the OpenResty main package.

Doing “Hello World” with the resty command, for example, is much easier.

resty -e 'print("Hello World")'

Notice the -e option.

Or run a Lua script on the terminal.

echo 'print("Hello World")' > hello.lua
cat hello.lua
resty hello.lua

So it’s also a great way to write new command-line applications using OpenResty.

Nonblocking I/O can also be implemented here.

time resty -e 'ngx.sleep(1) ngx.say("done")'

Let’s use the Cosocket API to connect to port 443 on

resty -e 'local sock = ngx.socket.tcp() print(sock:connect("", 443))'

Or use light threading.

resty -e 'ngx.thread.wait(ngx.thread.spawn(function () print("in thread!" ) end))'

You can also easily use Lua modules. Let’s create a Test module.

mkdir lua/
vim lua/test.lua

The lua/test.lua file looks like this.

local _M = {}

function _M.hello() print("Hello") end

return _M

We then use the -i option to add the lua/ directory to the Lua module search path.

resty -I lua/ -e 'require "test".hello()'

If there’s no -i option, it won’t be found.

resty -e 'require "test".hello()'

This is because the lua/ directory is not in the Lua module’s search path by default.

Standard Lua modules, such as, can be loaded directly.

resty -e 'local ok, stdout = require "".run([[echo ok]]) print(stdout)'

This module is used to run a small number of shell commands without blocking.

We can also define the Lua shared memory dictionary with the –shdict option.

resty --shdict 'dogs 10m' -e 'print(ngx.shared.dogs:set("age", 11))'

Multiple shared dictionaries can be defined this way.

resty --shdict 'dogs 7m' --shdict 'cats 5m' -e 'print(ngx.shared.dogs, " ", ngx.shared.cats)'

It also makes it easy to inject custom NGINX configuration code.

resty --http-conf 'lua_regex_match_limit 102400; ' -e 'print "ok"'

We can also play around with Luajit’s JIT compiler.

Let’s create a Lua script that runs hot.

echo 'local a = 0 for i = 1, 1e8 do a = a + 1 end print(a)' > bench.lua
cat bench.lua

Then disable the JIT compiler completely.

time resty -joff bench.lua

For comparison purposes, let’s check how fast it is with the JIT compiler enabled.

time resty bench.lua

Or we can use the -jv option to check the compiled Lua code path, or “traces”.

resty -jv bench.lua

Or more details, such as compiled bytecode dumps, IR code dumps, and machine code dumps.

resty -jdump bench.lua

You can find all the supported features at any time with the -h option.

resty -h

Or refer to its documentation through the “restydoc” tool.

restydoc resty-cli

If you install OpenResty from one of our pre-built binary packages, then you should install OpenResty-doc or the OpenResty-RestyDoc package.

dnf list installed openresty-doc

We’ll take a closer look at the “restydoc” tool in another dedicated video tutorial. If you enjoyed this tutorial, please subscribe to this blog site and our YouTube channel or Station B channel. Thank you very much!

<! — xray “Improve the performance of your application with OpenResty xray products” –>

About this article and associated videos

This article and the associated videos were generated entirely automatically by our OpenResty Demo system from a very simple script file.

About the author

Yicchun Zhang is the founder of OpenRESTY ®, an open source project, and OpenRESTY Inc. Founder and CEO of the company. He has contributed many third-party modules for Nginx, quite a few Nginx and Luajit core patches, and has designed products such as OpenResty Xray.

Pay attention to our

If you enjoyed this article, please follow our blog at OpenResty Inc. Also welcome to scan the code to pay attention to our WeChat official account:


We have provided the original English and Chinese versions (this article). We also welcome readers to provide translations in other languages. As long as the full text is translated without omission, we will consider using it. Thank you very much!