cd

Overview ¶

Package cd implements the cd builtin command.

cd — change the shell's working directory

Usage: cd [-LP] [-|DIRECTORY]

Change the shell's current working directory. The new directory must resolve to a path inside the AllowedPaths sandbox; targets outside the sandbox are rejected with exit 1 and the working directory is left unchanged.

Operands:

(none)       Change to the directory named by $HOME. If HOME is not
             set, an error is printed and exit 1 is returned.
-            Change to the directory named by $OLDPWD. If OLDPWD is
             not set (no successful cd has happened yet in this
             session), an error is printed and exit 1 is returned.
             On success the new absolute path is written to stdout
             (matching POSIX / bash).
DIRECTORY    Change to DIRECTORY. Relative paths are resolved against
             the shell's current working directory.

Flags:

-L, --logical   Resolve `..` lexically; symbolic links in the result
                are preserved. This is the default and matches POSIX.
-P, --physical  Resolve symbolic links before processing `..`. The
                resolution is sandbox-safe — components the sandbox
                cannot inspect (paths above the AllowedPaths root,
                or the root path itself if it is a symlink) pass
                through unresolved.
-h, --help      Print usage to stdout and exit 0.

If both -L and -P are given on the same invocation, the last one wins (matches POSIX and bash). Multiple positional operands are rejected with exit 1.

Side effects on success:

$OLDPWD is set to the previous working directory.
$PWD    is set to the new working directory.
The shell's tracked working directory is updated; subsequent file
operations resolve relative paths against the new directory.

Exit codes:

0  Success — the working directory was changed.
1  Error — invalid flag, missing target, target outside AllowedPaths,
   target is not a directory, or HOME/OLDPWD was required but unset.

Bash extensions intentionally not implemented:

-e          Only meaningful with -P when getcwd fails; not reachable
            here because rshell maintains the working directory
            internally via runner.Dir.
-@          AIX-only extended-attribute view.
CDPATH      Implicit directory search via $CDPATH is a path-confusion
            risk in a restricted shell.
~user       User-home expansion is a parser concern, not cd's.
cdable_vars Bash extension that treats unknown directories as variable
            names; off by default in bash too.

Sandbox-spanning invariants (`-P` divergence from bash):

The per-component walker for `-P` mode only resolves symlinks whose
parent component is inside `AllowedPaths`. Lstat against an
above-sandbox path returns `ErrPermission`, which the walker treats
as an opaque pass-through — so a sandbox-internal target reached
through an above-sandbox symlink (e.g. on macOS where `/tmp` is a
symlink to `/private/tmp`) is *not* resolved for that hop. The
final `changeDir` still rejects results outside the sandbox, so
this is a divergence from bash (which would resolve every hop),
not a security weakening. Operators running cd in a container-style
sandbox where the AllowedPaths root itself is a symlink should
expect cd -P to behave like cd -L for that root segment.