Commands¶
Run uncoded from the project's environment with uv run uncoded.
| To… | Use |
|---|---|
| Set uncoded up in a project | uv run uncoded init |
| Build or refresh the index and skills | uv run uncoded sync |
| Check generated files without writing | uv run uncoded check |
| Read a Python symbol's definition | uv run uncoded body <name_path> --in <file> |
| Find references to a Python symbol | uv run uncoded refs <name_path> --in <file> |
| Print the installed version | uv run uncoded --version |
Every command but init and --version runs inside a project. It finds the
configuration file in the current directory or the nearest directory above it.
If there is none, it exits with status 1.
usage: uncoded [-h] [--version] {init,sync,check,body,refs} ...
Build an index of a codebase for AI coding agents.
positional arguments:
{init,sync,check,body,refs}
init Set uncoded up in a project, then build its index and
skills.
sync Build or refresh the index and the skills.
check Verify that the generated files are current, without
writing. Exits non-zero if any file would change.
body Print the definition of a named symbol to stdout.
refs Find all references to a named symbol and print them
to stdout.
options:
-h, --help show this help message and exit
--version show program's version number and exit
init¶
usage: uncoded init [-h]
options:
-h, --help show this help message and exit
uv run uncoded init
Sets uncoded up in the project, then runs sync. Run it in the directory that
is to be the project directory.
If no configuration file is found in that directory or above it, init appends
a [tool.uncoded] table to the pyproject.toml in that directory. Its source
roots are whichever of src and tests exist, and its doc roots are whichever
of README.md, AGENTS.md and docs exist. If pyproject.toml does not
exist, or if none of those roots exist, init writes nothing and exits with
status 1. If init cannot write the configuration file, it says why and exits
with status 1. A configuration file that init finds is left as it is.
If sync fails, init stops there with exit status 1. After sync, init
says which files to commit, and prints the lines to add to AGENTS.md or
CLAUDE.md that tell agents to load the navigation skills. It does not edit
those files. Running it again does no harm.
sync¶
usage: uncoded sync [-h]
options:
-h, --help show this help message and exit
uv run uncoded sync
Builds or refreshes the index and the skills. Output lists files created, updated, or removed. Running it from a subdirectory writes the same files, in the project directory.
Files that cannot be parsed or decoded are skipped with a warning, and the
output ends with a line that says how many files were skipped. A skipped file
does not change the exit status. Invalid configuration or roots, or a generated
file that cannot be read, written or removed, cause exit status 1.
check¶
usage: uncoded check [-h]
options:
-h, --help show this help message and exit
uv run uncoded check
Runs the same pipeline as sync without changing files.
| Status | Meaning |
|---|---|
0 |
All generated files are current. |
1 |
A file would be created, updated, or removed, the configuration is invalid, or a generated file cannot be read. |
The index is never committed, so in a fresh checkout check always reports it
as stale. It is not a check for CI. See
Keep the index current.
body¶
usage: uncoded body [-h] --in PATH name_path
positional arguments:
name_path Name path: one segment for top-level, two for Class/member.
options:
-h, --help show this help message and exit
--in PATH Source file path (relative to current directory).
uv run uncoded body greet --in src/greetings.py
uv run uncoded body Greeter/greet --in src/greetings.py
Prints the named symbol's source to standard output, exactly as written in the
file. These examples assume a greet function or a Greeter.greet method in
src/greetings.py.
Use one name for a top-level function, class, module assignment, or Python 3.12
type statement. Use Class/member for a method, property or assignment in a
class body. Deeper paths and empty segments are unsupported.
The --in path is relative to the current directory, not the configuration
file. It must be inside the project directory, once symbolic links are resolved.
Run body from the project directory, so that the namespace map's paths can be
passed to --in unchanged.
refs¶
usage: uncoded refs [-h] --in PATH name_path
positional arguments:
name_path Name path: one segment for top-level, two for Class/member.
options:
-h, --help show this help message and exit
--in PATH Source file path (relative to current directory).
uv run uncoded refs greet --in src/greetings.py
uv run uncoded refs Greeter/greet --in src/greetings.py
Finds every reference to the symbol: its definition, each import of it, and each
use of it. Names and --in paths follow the same rules as body. Each result
is printed as:
path:line:column
Positions are one-based. Results are sorted by path and position. Paths within
the current directory are relative; other paths are absolute. Every path uses
/ to separate directories, on Windows too.
Reference resolution uses the pinned ty language server through uvx. The
first call may download it. uvx must be on PATH.
--version¶
uv run uncoded --version
Prints uncoded and the installed version, such as uncoded <version>.
Lookup errors¶
body and refs exit with status 1 if the --in file is outside the project
directory, the source cannot be read or parsed, the symbol is missing, or its
name path is unsupported. refs also exits with status 1 if ty fails, and
passes on what ty and uvx wrote about why. Missing required arguments exit
with status 2.