Command Reference

📖 Command reference

Every command, every flag, and the things a script can rely on.

crower <command> --help prints the same information for one command. This page is the version you can read without a terminal.

---

🧭 The contract

Four rules hold for every command. A script may depend on all of them.

Results go to stdout	the table of list, the rows of search
Diagnostics go to stderr	prompts, status lines, warnings, errors
Exit 0	the work happened — or the user declined, and nothing was the answer
Exit 1	the work did not happen

# only the table reaches the file
crower list > commands.txt

# a failure is visible to the script
if ! crower execute deploy; then echo "deploy failed" >&2; fi

A prompt with no input available — a closed stdin, or --no-input — is an error, not an empty answer. The run fails instead of waiting.

⚙️ Global flags

These work on every command.

Flag	Short	Meaning
--config <path>		configuration file (default $HOME/crower/crower.yaml)
--no-input		never prompt; fail instead of waiting for a person
--version	-v	print the version
--upgrade		upgrade to the latest release
--check		check whether a newer release exists

--config and --no-input are persistent: every subcommand inherits them.

--setup <name> selects a named command setup (~/crower/setups/<name>/). It applies when --config is not given; CROWER_SETUP sets the same default. The default installation keeps its old path and history.

🤖 Machine-readable results

list and search accept --json: the result becomes one JSON object on stdout, diagnostics stay on stderr, and the exit status is unchanged.

crower list --json | jq -r '.commands[].name'

Command	Object
crower list	{"commands":[{"row":0,"name":"gs","aliases":["g"],"exec":"git status"}]}
crower list --history	{"history":[{"version":1,"file":"00001.yaml","timestamp":"2026-01-02T15:04:05Z","operation":"create","command":"gs","note":"…"}]}
crower list --folder <dir>	{"entries":[{"name":"a.txt","dir":false,"size":12,"mode":"-rw-r--r--","modified":"…"}]}
crower list --process	{"processes":[…]}
crower list --system	{"variables":[{"name":"PATH","values":["…"]}]}
crower list --syspath	{"variable":{"name":"PATH","values":["…"]}}
crower search	{"search":{"kind":"file","query":"main","path":".","results":["…"]}}

Any other command rejects --json as an unknown flag: a global switch a command silently ignored would report success without honouring it.

---

crower list --json rows carry description, params, shell, cwd, env and timeout when the command declares them. The first two are metadata; the rest say how it runs.

➕ crower create

crower create [name] [exec]

Create a command, a file or a folder. With no arguments, crower asks for each field.

Flag	Short	Meaning
--alias <a,b>	-a	add aliases (comma-separated, repeatable)
--icon <marker>		a short marker (an emoji) shown beside the command in the window
--group <name>		the group the command belongs to
--description <text>		what the command is for
--params <a,b>		positional parameters (env,region)
--cwd <dir>		working directory the command runs in
--shell <name>		shell that runs the command (sh, pwsh, cmd)
--timeout <dur>		longest the command may run (120s)
--process <name>	-p	create the command from a running process; the argument is its name or pid
--file	-f	treat every argument as a file path to create
--folder	-o	treat every argument as a folder path to create
--script		create a script file that the command runs
--system		create a system variable
--syspath		add a directory to the system PATH
--execute		create a command from the last command you ran

crower create greet "echo hello"
crower create greet "echo hello" --alias hi
crower create --file notes.txt
crower create --folder reports
crower create -p server nginx

A command runs through sh -c on Linux and macOS, and cmd /c on Windows, unless it declares its own Shell. A Steps command runs its steps instead of its exec; execute refuses to run one with parameters it cannot apply.

✏️ crower update

crower update [command]

Change a command's name, aliases, exec or execution metadata. The command is found by name or alias.

Flag	Short	Meaning
--name <name>	-n	new name
--alias <a,b>	-a	new alias list, replacing the old one
--exec <line>	-e	new command line
--icon <marker>		new icon; an empty value removes it
--group <name>		new group; an empty value removes it
--description <text>		what the command is for; empty removes it
--params <a,b>		positional parameters; empty removes them
--cwd <dir>		working directory; empty removes it
--shell <name>		shell that runs the command; empty removes it
--timeout <dur>		longest the command may run; empty removes it
--last	-l	update the last executed command
--create	-c	update the last created command
--execute	-x	update the last updated command

crower update greet --exec "echo hi"
crower update greet --name hello --alias hi
crower update --last

With no field given, crower asks for each one. A Steps command keeps its steps: update has no flag for them, so it never replaces them.

🗑️ crower delete

crower delete [command]

Delete a command, a file or a folder.

Flag	Short	Meaning
--create	-c	delete the last created command
--update	-u	delete the last updated command
--execute	-x	delete the last executed command
--history		delete one history entry and its snapshot
--file	-f	treat every argument as a file path
--folder	-o	treat every argument as a folder path
--system		delete a system variable
--syspath		remove a directory from the system PATH

crower delete greet
crower delete hi
crower delete --file notes.txt
crower delete --create

With no arguments crower asks which command to delete. Deleting is recorded in the history, so revert can bring the command back.

📋 crower list

crower list [flags]

Flag	Short	Meaning
--process	-p	list running processes
--history	-i	list the history, newest first
--folder <dir>	-o	list the files in a folder
--system		list system variables
--syspath		list the system PATH entries
--json		one JSON object on stdout instead of a table

crower list
crower list --history
crower list --folder ~/projects
crower list --json

With no flag, crower lists the managed commands in the order they were saved.

▶️ crower execute

crower execute <command> [params...]

Run a managed command by name or alias. crower <name> is the same thing.

Flag	Short	Meaning
--last	-l	run the last executed command
--create	-c	run the last created command
--update	-u	run the last updated command

crower execute greet
crower greet
crower execute --last

Parameters after the command fill {1}, {2}, … in its steps; {} takes the rest. Each parameter is quoted before it reaches the shell.

A command may declare the shell it needs and the folder it runs in. Shell is sh, pwsh or cmd (the named shell must be installed); empty keeps the platform's own shell (sh on Linux and macOS, cmd on Windows). Cwd is the working directory, and a leading ~ is the user's home. Every step of a Steps command inherits both. An unknown shell, or a folder that does not exist, fails before anything runs. Set both in the configuration file or in a pack; create and update have no flags for them yet.

Env merges entries over the process environment. A value that is exactly ${VAR} reads VAR from the environment, and an unset variable is an error rather than an empty value. A literal under a secret-looking key (*TOKEN*, *SECRET*, *PASSWORD*, *_KEY*, …) is refused on export, import, save and execute: a pack carries placeholders, never secrets. A hand-edited config with one still loads, with a warning, and list --json redacts it. Timeout is a Go duration (120s, 2m) applied to each step; an overrun kills the step and the error names the limit.

📂 crower open

crower open [path...]

Flag	Short	Meaning
--file	-f	open a file with the system opener
--folder	-o	open a folder with the system opener
--system	-s	open the system settings

crower open                 # the configuration file
crower open --file notes.txt
crower open --folder .

📄 crower copy

crower copy <source...> <destination>

Copy files or folders. The last argument is the destination.

crower copy notes.txt ~/backup
crower copy a.txt b.txt ~/backup
crower copy ./reports ~/backup

🚚 crower move

crower move <source...> <destination>

Move files or folders. The last argument is the destination.

crower move notes.txt ~/archive
crower move ./reports ~/archive

🔍 crower search

crower search <term> [path]

Flag	Short	Meaning
--file	-f	search for a file name
--folder	-o	search for a folder name
--browser	-b	search the web in the default browser
--json		one JSON object on stdout instead of a table

crower search report ./notes
crower search --folder projects ~
crower search --browser "golang context"

🗜️ crower extract

crower extract <archive...>

Unpack .zip, .tar, .tar.gz, .7z, .rar and friends.

Flag	Short	Meaning
--out <dir>	-o	extract into this folder instead of the archive's own

crower extract files.zip
crower extract files.zip --out ./build
crower extract "*.zip"

↩️ crower revert

crower revert <steps>

Undo operations, newest first. The argument is how many operations to roll back: revert 1 undoes the last one, revert 3 undoes the last three.

crower revert 1
crower revert 3

crower list --history shows what is there. Reverting writes the restored command map back and drops the entries it passed. A snapshot records the state after its operation, so undoing one operation restores the state before it — which is why revert 1 after a delete brings the command back.

♻️ crower restore

crower restore <command>

Bring back a command from the snapshot of a past operation, by name or alias. This is how a deleted or overwritten command comes back without undoing everything after it.

crower restore greet

🔄 crower reset

crower reset

Delete every managed command. The table is shown first and nothing happens unless you confirm. History snapshots are left alone: crower list --history still works and crower revert can bring the commands back.

crower reset

📤 crower export

crower export [name]

Export one command, or all of them, to a TOML file for sharing.

Flag	Short	Meaning
--out <path>	-o	write here instead of the default file

crower export
crower export greet
crower export --out ./commands.toml

📥 crower import

crower import <file>

Import commands from a TOML file.

Flag	Meaning
--overwrite	replace a command that already exists with the same name

crower import ./commands.toml
crower import ./commands.toml --overwrite

Names and aliases share one namespace: an import that would collide is renamed rather than silently shadowing a command.

🤝 crower share

List and pull command packs from a registry.

crower share list

List the packs the registry publishes.

crower share list

crower share pull

Pull a pack into the command set.

crower share pull tools

🎛️ crower gui

Open the interactive terminal UI.

crower gui

🖼️ crower-gui

Every platform archive contains crower-gui, the Fyne desktop application. It is not a crower subcommand; extract the archive and launch it. The CLI binaries are cgo-free and need no display.

crower-gui                   # open the window
crower-gui --config FILE     # another configuration file
crower-gui --setup NAME      # a named setup

It opens the window whatever the arguments are: an unknown argument is ignored, because a window has no subcommands and a double-click must never reach a command parser. --help prints the three lines above and exits.

---

🗂️ crower setup

crower setup list                 # the default setup and every named one
crower setup new streamer         # create ~/crower/setups/streamer/
crower setup use streamer         # make it the default for future runs
crower setup show                 # active setup, config path, command count
crower setup delete gaming --force

Each setup keeps its own commands and its own history. The default setup keeps ~/crower/crower.yaml; nothing migrates.

crower setup list

Prints default and every folder under ~/crower/setups/, marking the active one.

crower setup new

Creates an empty named setup. The name must be a slug (letters, digits, -, _, .).

crower setup use

Persists the default setup for future runs (the same as --setup and CROWER_SETUP). The setup must exist.

crower setup show

Prints the active setup, its configuration path and how many commands it holds.

crower setup delete

Removes a named setup and its history. The active setup is protected unless --force is passed; the default setup is not a folder and is never deleted here.

🩺 crower doctor

crower doctor
crower doctor --json

Shows the configuration file and folder, whether the folder is writable, how many commands and history entries exist, the update-check mode, the detected shell and editor, whether the diagnostics stream is a terminal, and the platform. --json prints the same as one object.

It reads only: nothing is created beyond the config folder the run needs.

🚀 crower init

crower init            # show the line for your shell
crower init --apply    # append it to the startup file

Prints the PATH line for bash, zsh or fish and where it goes. --apply appends it once; a second run is a no-op. It also prints the completion command for the detected shell.

🧾 Exit codes

Status	Meaning
0	the work happened, help was printed, or the user declined a confirmation
1	the command failed; the reason is one line on stderr

Nothing else is used: a script can test the status without decoding it.

🔤 A note on shorthands

-o means --folder on create, delete, list, search and open, and --out on extract and export. It is the one shorthand that changes meaning between commands; write the long flag in scripts.