Use ri to find Ruby APIs without leaving the terminal

You will use ri, Ruby's command-line API reference, to find a class, inspect a method, search the installed documentation and read a gem's README. This is useful when you need an API detail without opening a browser or guessing from memory. Allow about ten minutes for the first pass. You need Ruby's RDoc data installed; the examples below use the installed Ruby 3.2 package and ri 6.5.0.

1. Confirm which ri you are running

The unversioned ri command and ri3.2 are aliases for this guide's purpose. Check both the path and version before debugging a documentation mismatch. This needs no elevated privileges.

$ command -v ri
/usr/bin/ri
$ command -v ri3.2
/usr/bin/ri3.2
$ ri3.2 --version
ri3.2 6.5.0

Checkpoint: if the version or path differs, keep using the command you just checked and treat its local output as authoritative. Do not add sudo just because a lookup failed. The command reads documentation; it does not need to change the Ruby installation.

2. Look up a class or method

Pass a name after the options. A class or module name shows its reference page. A name such as File.new selects a method, while Array#first clearly selects an instance method. A dot can match either class or instance methods, # selects an instance method, and :: selects a class method.

$ ri3.2 --no-pager File.new
$ ri3.2 --no-pager Array#first
$ ri3.2 --no-pager Array::new

The output begins with the selected method's signature and then its description. Use --no-pager in scripts and in copied examples so output goes directly to standard output. Without it, ri can send output through a pager depending on the terminal and formatter defaults.

Class names may be abbreviated to the shortest unambiguous form. That saves typing, but it also creates a distraction when a new gem adds a competing name. If ri reports ambiguity, use the complete class or module name and select the entry you actually mean.

Names containing punctuation need shell quoting. This keeps the shell from interpreting the characters before ri sees them:

$ ri3.2 --no-pager 'Array.[]'
$ ri3.2 --no-pager 'String#compact!'

Checkpoint: a successful lookup prints a heading and reference text. An empty or missing result is not evidence that the Ruby method does not exist; it may mean that its RDoc data is absent or that the name was entered for the wrong receiver.

3. Browse what the local index knows

Use --list to list classes known to ri. It can produce a long result, so inspect a small prefix first. The pipe limits what you see but does not change the index.

$ ri3.2 --no-pager --list | head -n 12
ACL
ACL::ACLEntry
ACL::ACLList
ARGF
Abbrev
Addrinfo
ArgumentError
Array
Base64
BasicObject
BasicSocket
Benchmark

Your list can differ when site libraries, gems or user documentation have changed. To see the directories ri searches, run:

$ ri3.2 --list-doc-dirs
/usr/share/ri/3.2.0/system
/usr/share/ri/3.2.0/site
/home/andy/.local/share/rdoc

The last path is user-specific. The manual also identifies ~/.rdoc as the home documentation location; the exact effective path can depend on the Ruby and RDoc installation. Use the command's output rather than assuming a directory exists.

4. Separate standard library, site, gem and home documentation

By default, ri includes the system, site, gem and home documentation sources. Use the source switches when a result from one area is confusing or you need a reproducible lookup. For example, this asks only the Ruby standard library data for File:

$ ri3.2 --no-pager --format=rdoc --system File
= File < IO

(from ruby core)
------------------------------------------------------------------------
A File object is a representation of a file in the underlying platform.

The corresponding switches are --system, --site, --gems and --home. Their default is enabled. The manual states that specifying these options limits the search to the selected directories, so do not add --system to a normal lookup unless you intend to exclude the others.

For documentation in another directory, add it with --doc-dir=DIRNAME. It can be repeated. If you want only that directory, combine it with --no-standard-docs:

$ ri3.2 --no-pager --no-standard-docs --doc-dir=/path/to/rdoc-data CustomClass

/path/to/rdoc-data is a placeholder, not a directory created by ri. Replace it only with a real RDoc data directory. This command only reads that location.

5. Read a gem README or change the output format

Prefix a gem file with the gem name and a colon. A trailing colon lists files in that gem, while a name such as rdoc:README selects its README. The extension can be omitted when the name is unambiguous.

$ ri3.2 --no-pager rdoc:README
$ ri3.2 --no-pager rdoc:

For output that is easier to redirect or process, choose a formatter explicitly. The documented formatters are ansi, bs, markdown and rdoc:

$ ri3.2 --no-pager --format=markdown Array#first > array-first.md
$ test -s array-first.md && echo "reference written"
reference written

Keep the redirection target separate from the source documentation. Shell > truncates an existing file before ri runs. If the destination matters, choose a new filename first, inspect it, then replace the old file deliberately.

6. Make repeat lookups predictable

Use --width=WIDTH when a fixed line width matters in a review or generated file. The pager can also be selected with RI_PAGER or PAGER. The RI environment variable supplies options before the command-line options, so inspect it when ri behaves differently between shells:

$ printf 'RI=%s\n' "${RI-}"
$ printf 'RI_PAGER=%s\n' "${RI_PAGER-}"
$ printf 'PAGER=%s\n' "${PAGER-}"
$ env RI= ri3.2 --no-pager --width=100 File.new | sed -n '1,12p'

Do not copy an unknown RI value into a script. It changes every ri invocation in that environment and can quietly add a directory, formatter or pager option. Clearing it for one command is a safe diagnostic; it does not alter your shell permanently.

7. Treat the server option as a deliberate service

--server[=PORT] runs an RDoc server, using port 8214 when no port is supplied. This is different from a one-shot lookup: it opens a listening service and can expose documentation to clients that can reach the bound address. Use it only when you understand the network boundary and have a controlled way to stop the process. Do not paste it into a startup file as a quick workaround for a failed lookup.

The ordinary reference workflow has no persistent state and no undo step. If you experimented with output redirection, remove only an output file you created and have checked before deleting it. Never remove the RDoc directories merely to repair one missing result; rebuild or reinstall documentation through your normal Ruby package process after identifying the package that owns it.