Aliases
cradle run <ref> and cradle schedule <action> <ref> both accept a bare name instead of a path. A bare name is looked up in a global name → folder map at ~/.cradle/settings.json, so agents you keep far from any project don't need a full path from every working directory:
With that in place, cradle run my-agent works from anywhere and starts in ~/dev/my-project/. cwd is optional; without it, the run starts in your terminal's current directory. Both path and cwd accept absolute paths, ~/, or $HOME/. An incorrectly shaped cwd warns and falls back to the terminal directory without dropping the alias; a cwd that is not an existing directory stops the run before setup.
Resolution
my-agent./my-agent only when no alias is defined../my-agent, ../x, /abs/x, ~/x, .A bare name is anything without a path separator that doesn't start with . or ~. Anything already path-shaped skips the alias table entirely.
The alias path resolves to an absolute path before the agent folder loads. cradle run my-agent and cradle run ~/dev/agents/my-agent/ share the same state dir and agent ID, but only the named alias uses its configured cwd. The effective cwd is used for the pi process and the sandbox's read-write project grant or mount. A scheduled task's own cwd takes precedence over the alias default.
Shadowing
When an alias shadows a same-named directory in your current working directory, cradle warns and points at ./my-agent as the escape hatch to reach the local directory instead of the alias.
When a bare name matches neither an alias nor a cwd-relative directory, the error names both misses so you know which lookup failed.
Config is not state
~/.cradle/settings.json's path derives from your home directory only, entirely apart from CRADLE_STATE_DIR (which controls where session history and generated extensions live — see Commands). Redirecting where state lives never silently moves where aliases are read from.
The filename collides with an agent folder's own pi-native settings.json, but they're different files with different schema authorities: cradle owns the global alias file, so an unknown key there warns. An agent folder's own settings.json is pi's schema — cradle stays silent on keys it doesn't recognize there and defers to pi.