How to fix failed to change directory error in OpenCode and Linux CLI tools

When working with terminal utilities on Linux, path resolution failures are common, but the root cause is not always what it seems at first glance.

Recently, while opening OpenCode in a terminal session, I entered a command and encountered this error:

root@servidor:~# opencode cli
Error: Failed to change directory to /root/cli

My initial thought was that a required subcommand was missing or that the installation had broken. However, looking into the argument parser and operating system calls revealed the actual cause: a misunderstanding of CLI positional arguments combined with relative path resolution in Linux.

Here is what caused this error and how to fix it immediately.

Why does this error happen?#

The message Error: Failed to change directory to /root/cli is not a permission issue (Permission denied). Even when running as root, the operating system rejected the request because the directory simply did not exist.

The underlying issue comes from how OpenCode handles command-line arguments:

1. OpenCode is already the CLI#

Many developer tools use explicit subcommands (such as docker compose or gh cli). Because of that habit, it is easy to assume that launching the terminal interface requires typing opencode cli.

OpenCode works differently:

• The default interactive terminal interface (TUI) opens by running opencode alone.
• The standard syntax of the command is: opencode [project].
• Because there is no built-in subcommand named cli, the tool interprets cli as the directory path of the project you want to inspect.

2. Relative path resolution to absolute path#

On Linux, when you provide a relative path (one without a leading /), the process resolves that path relative to your current working directory ($PWD).

Because my terminal session was in /root and I passed cli, OpenCode resolved the target path to /root/cli and attempted a system call (such as chdir() in C or process.chdir() in Node.js/Bun).

Because /root/cli did not exist on the filesystem, the operating system returned ENOENT (No such file or directory), which OpenCode displayed as:

Error: Failed to change directory to /root/cli

How to resolve the error#

Depending on what you intended to do, here are the direct solutions:

Case 1: You just want to start OpenCode in the current folder#

If you want to open the interactive terminal in your current directory, run:

opencode

Or pass the current directory explicitly:

opencode .

The dot (.) specifies the current directory: OpenCode starts in place without searching for nonexistent folders.

Case 2: You want to open an existing project#

If your project is located elsewhere, provide the actual path:

opencode /var/www/my-project

Or switch to the project directory first:

cd /var/www/my-project
opencode

Case 3: You actually need a project folder named CLI#

If your workflow requires a project directory named cli inside your current directory, create it before launching OpenCode:

mkdir -p /root/cli
opencode cli

The -p flag ensures the command succeeds without error if the directory already exists.

Practical commands for inspecting paths and executables#

When a command-line tool fails with path errors, run this quick diagnostic check:

1. Confirm your current working directory#

pwd

Shows the exact location where your shell is currently operating.

2. Check the contents of the current folder#

ls -la

Verifies whether the file or directory you passed as an argument actually exists.

3. Trace where the executable comes from#

which opencode
type -a opencode

The type -a command is particularly helpful because it shows whether opencode is a raw binary, a shell alias, or a wrapper script that might be injecting hidden arguments.

4. Inspect official CLI arguments#

Instead of guessing flags or subcommands, check the built-in help:

opencode --help

In the help output, valid subcommands include opencode run, opencode web, opencode serve, opencode models, and opencode [project]. There is no cli subcommand.

Best practices for passing paths to terminal tools#

Directory errors usually occur when subcommands are confused with positional path arguments.

To prevent these issues:

1. Use the current folder as an anchor: When you are already in the project directory, run opencode alone or pass . as the target.
2. Use absolute paths in automation scripts: When writing Bash scripts or cron jobs, avoid relative paths. Always specify full paths such as /var/www/site so execution does not depend on the session $PWD.
3. Verify directory existence before execution: In shell scripts, add a quick safety check with test -d /path || mkdir -p /path.

With these simple habits, tools like OpenCode start in the right workspace without crashing in the terminal.

See also

Linux Extracting 7z archives in Linux via CLI: from basics to low-level troubleshooting

Infrastructure Linux troubleshooting: when 'command not found' made me revisit PATH and sudo su

Linux Killing cascading process trees in Linux with pkill without leaving orphaned children

This post is licensed under CC BY-NC.