Skip to content

yangshun/tree-node-cli

BranchesTags

Repository files navigation

tree-node-cli

Lists the contents of directories in a tree-like format, similar to the Linux tree command. Both CLI and Node.js APIs are provided.

tree is a command that produces a nicely-formatted indented output of directories and files. When a directory argument is given, tree lists all the files and/or directories found in the given directory.

Note: Symlinks are not followed. Directories that cannot be opened (e.g. due to permission errors) are listed with [error opening dir] instead of crashing, matching Linux tree behavior.

Quickstart

Instantly execute the command in your current directory via npx / pnpx / bunx / yarn dlx:

npx tree-node-cli

Installation

npm install tree-node-cli
# or globally
npm install -g tree-node-cli

Example

$ tree -L 2
tree-node-cli
├── CNAME
├── LICENSE
├── README.md
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── src
│   ├── __tests__
│   ├── cli.ts
│   ├── index.ts
│   └── types.d.ts
├── tsconfig.json
└── tsdown.config.ts

Note

gitignore is respected by default so node_modules and other common files/directories are excluded automatically. Use --no-gitignore to show them.

CLI

tree [options] [path/to/dir]

Important

Use the command treee on Windows and Linux to avoid conflicts with built-in tree command.

The following options are available:

$ tree --help

Usage:
  $ tree <command> [options]

Options:
Listing options:
  -a, --all-files           All files, including hidden files, are printed.
  -d, --dirs-only           List directories only.
  -f, --full-path           Print the full path prefix for each file.
  -L, --max-depth <n>       Max display depth of the directory tree.
  -I, --exclude <patterns>  Exclude files that match the pattern. | separates
                            alternate patterns. Wrap your entire pattern in double
                            quotes. E.g. "node_modules|coverage".
  --gitignore               Respect .gitignore files (enabled by default).
                            Use --no-gitignore to disable.
  --prune                   Remove empty directories from output.

File options:
  -Q, --quote               Quote filenames in double quotes.
  -p, --permissions         Show file type and permissions.
  -s, --sizes               Print the size of each file in bytes along with the name.
  -h, --human-readable      Print file sizes in human-readable format (powers
                            of 1024). Implies -s.
  --si                      Print file sizes using SI units (powers of 1000).
                            Implies -s.
  --du                      For each directory report its size as the accumulation
                            of sizes of all its files and sub-directories. Implies -s.
  -D, --date                Show last modification time for each entry.
  -F, --trailing-slash      Append a '/' for directories.

Sorting options:
  -v, --version-sort        Sort the output by version (natural sort of numbers
                            within text).
  -t, --sort-mtime          Sort the output by last modification time.
  -c, --sort-ctime          Sort the output by last status change time.
  -U, --unsorted            Do not sort. List files in directory order.
  -r, --reverse             Sort the output in reverse alphabetic order.
  --dirs-first              List directories before files.
  --files-first             List files before directories.
  --sort <type>             Sort the output by type: name, version, mtime,
                            ctime, size.

Graphics options:
  -i, --no-indent           Print entries without tree indentation lines.
  -S, --line-ascii          Turn on ASCII line graphics.

Output options:
  -J, --json                Output the tree as a JSON structure.

Misc options:
  --help                    Display this message
  --version                 Display version number

Tip

To exclude the contents of a directory while still printing the directory itself, use a trailing slash with the -I option (e.g., -I "directory/").

For the Node.js API, provide a regex matching the directory contents (e.g., /directory\//). Directories listed in .gitignore (e.g. node_modules) are already excluded by default, use --no-gitignore in combination with -I "directory/" if you want them to show up.

Node.js API

tree(path, options?)

Returns the tree as a formatted string.

import { tree } from 'tree-node-cli';

const string = tree('path/to/dir', {
  allFiles: true,
  exclude: [/vendor/, /lcov/],
  maxDepth: 4,
});

console.log(string);

treeJson(path, options?)

Returns the tree as a structured TreeJsonEntry object (or null if the path is excluded).

// Discriminated union — `contents` only exists on directories
type TreeJsonEntry =
  | {
      type: 'directory';
      name: string;
      contents: TreeJsonEntry[];
      size?: number;
      mode?: string;
      time?: string;
    }
  | { type: 'file'; name: string; size?: number; mode?: string; time?: string };
// size: present when `sizes: true`
// mode: present when `permissions: true`
// time: present when `date: true`
// error: present when the directory could not be opened (e.g. permission denied)
import { treeJson } from 'tree-node-cli';

const result = treeJson('path/to/dir', { sizes: true });
console.log(result);
// { type: 'directory', name: 'dir', size: 4096, contents: [...] }

Options

options is a configuration object with the following fields:

Field Default Type Description
allFiles false boolean All files, including hidden files, are printed.
dirsOnly false boolean List directories only.
fullPath false boolean Print the full path prefix for each file.
maxDepth Number.POSITIVE_INFINITY number Max display depth of the directory tree.
exclude [] RegExp[] An array of regex to test each filename against. Matching files will be excluded and matching directories will not be traversed into. To exclude a directory's contents while still showing the directory itself, use a regex that matches the path with a trailing slash (e.g., /vendor\//).
gitignore true boolean Respect .gitignore files when inside a git repository. Use --no-gitignore to disable.
prune false boolean Remove empty directories from output.
quote false boolean Quote filenames in double quotes.
permissions false boolean Show file type and permissions (e.g. [drwxr-xr-x]).
sizes false boolean Print the size of each file in bytes along with the name.
humanReadable false boolean Print file sizes in human-readable format (powers of 1024). Implies sizes.
si false boolean Print file sizes using SI units (powers of 1000). Implies sizes.
du false boolean For each directory, report its size as the accumulation of sizes of all its files and sub-directories. Implies sizes.
date false boolean Show last modification time for each entry.
trailingSlash false boolean Append a / for directories.
sortBy 'name' string Sort the output. Options: 'name', 'version', 'mtime', 'ctime', 'size'.
unsorted false boolean Do not sort. List files in directory order.
reverse false boolean Sort the output in reverse alphabetic order.
dirsFirst false boolean List directories before files.
filesFirst false boolean List files before directories.
noIndent false boolean Print entries without tree indentation lines.
lineAscii false boolean Turn on ASCII line graphics.

License

MIT

About

List directory contents in a tree-like format, similar to the Linux tree command

tree-cli.js.org

Topics

linux cli tree node directory file hacktoberfest

Resources

Readme

License

MIT license
Activity

Stars

266 stars

Watchers

3 watching

Forks

28 forks
Report repository

Releases 13

v2.0.0 Latest
Mar 7, 2026
+ 12 releases

Contributors

Languages