Commands

In vimiv all keybindings are mapped to commands.

Most of the commands can also be run from the command line but some are hidden as they are not useful to run by hand. A typical example is the :command command which enters the command line.

Every command is limited to its mode. This allows commands with equal names to do different things depending on the mode they are run in. For example the :zoom command rescales the image in image mode but changes the size of thumbnails in thumbnail mode. This also prevents running commands that are useless in the current mode. Commands available in the special global mode can be run in image, library and thumbnail mode.

Below is a complete list of all commands in every mode.

Global

Overview of global commands

Command	Description
alias	Add an alias for a command.
bind	Bind keys to a command.
command	Enter command mode.
copy-image	Copy currently selected image to system clipboard.
copy-name	Copy name of current path to system clipboard.
delete	Move one or more images to the trash directory.
enter	Enter another mode.
fullscreen	Toggle fullscreen mode.
help	Show help on a command or setting.
history-clear	Clear the command history.
keybindings	Show a pop-up with keybindings information.
log	Log a message with the corresponding log level.
mark	Mark one or more paths.
mark-clear	Clear all marks.
mark-rename	Rename marked images with a common base.
mark-restore	Restore the last cleared marks.
next	Select next image.
nop	Do nothing.
open	Open one or more paths.
paste-name	Paste path from clipboard to open command.
prev	Select previous image.
print-stdout	Print text to the terminal.
quit	Quit vimiv.
rename	Rename images with a common base.
repeat-command	Repeat the last command.
scale	Scale the image.
search	Start a search.
search-next	Continue search to the next match.
search-prev	Continue search to the previous match.
set	Set an option.
sleep	Sleep for a given number of seconds.
spawn	Spawn a command in a sub-shell.
tag-delete	Delete an existing tag.
tag-load	Load images from a tag into the current mark list.
tag-open	Open images from a tag in image mode.
tag-write	Write marked paths to a tag.
toggle	Toggle one mode.
unbind	Unbind a keybinding.
undelete	Restore a file from the trash directory.
version	Show a pop-up with version information.
welcome-to-qt	Show a pop-up with a welcome message for users coming from gtk.

alias

Add an alias for a command.

syntax: :alias name command [--mode=MODE]

The command can be a vimiv command like quit or an external shell command like !gimp.

positional arguments:

• name: Name of the newly defined alias.

• command: Name of the command to alias.

optional arguments:

• --mode: Mode in which the alias is valid. Default: global.

bind

Bind keys to a command.

syntax: :bind keybinding command [--mode=MODE]

positional arguments:

• keybinding: The keys to bind.

• command: The command to execute with optional arguments.

optional arguments:

• --mode: The mode to bind the keybinding in. Default: current.

command

Enter command mode.

syntax: :command [--text=TEXT]

optional arguments:

• --text: String to append to the : prefix.

copy-image

Copy currently selected image to system clipboard.

syntax: :copy-image [--primary] [--width=WIDTH] [--height=HEIGHT] [--size=SIZE]

optional arguments:

• --primary: Copy to primary selection.

• --width: Scale width to the specified value.

• --height: Scale height to the specified value.

• --size: Scale longer side to the specified value.

count: Equivalent to the --size option

copy-name

Copy name of current path to system clipboard.

syntax: :copy-name [--abspath] [--primary]

optional arguments:

• --abspath: Copy absolute path instead of basename.

• --primary: Copy to primary selection.

delete

Move one or more images to the trash directory.

syntax: :delete path [path ...]

positional arguments:

• paths: The path(s) to the images to delete.

optional arguments:

• --ask: Prompt for confirmation before deleting the images.

Note

This only deletes images, not any other path(s).

enter

Enter another mode.

syntax: :enter mode

positional arguments:

• mode: The mode to enter (image/library/thumbnail/manipulate).

fullscreen

Toggle fullscreen mode.

help

Show help on a command or setting.

syntax: :help topic

positional arguments:

• topic: Either a valid :command or a valid setting name.

Hint

For commands help :command is the same as command -h.

history-clear

Clear the command history.

This clears the history of all modes unless --mode is passed.

syntax: :history-clear [--mode]

optional arguments:

• --mode: Clear the history of the current mode only.

keybindings

Show a pop-up with keybindings information.

syntax: :keybindings [--columns=N]

optional arguments:

• --columns: Number of columns to split the bindings in.

log

Log a message with the corresponding log level.

syntax: :log level message

positional arguments:

• level: Log level of the message (debug, info, warning, error, critical).

• message: Message to log.

mark

Mark one or more paths.

syntax: :mark path [path ...] [--action=ACTION]

Hint

:mark % marks the current path.

positional arguments:

• paths: The path(s) to mark.

optional arguments:

• --action: One of toggle/mark/unmark. Toggle, the default, inverses the mark status of the path(s). Mark forces marking while unmark forces removing the mark.

mark-clear

Clear all marks.

Hint

It is possible to restore the last cleared marks using mark-restore.

mark-rename

Rename marked images with a common base.

syntax: :mark-rename base [--start=INDEX] [--separator=SEPARATOR] [--overwrite] [--skip-image-check]

Example::

:mark-rename my_mark would rename all marked images to my_mark_001, my_mark_002, …, my_mark_NNN.

positional arguments:

• paths: The path(s) to rename.

• base: Base name to use for numbering.

optional arguments:

• --start: Index to start numbering with. Default: 1.

• --separator: Separator between base and numbers. Default: ‘_’.

• --overwrite: Overwrite existing paths when renaming.

• --skip-image-check: Do not check if all renamed paths are images.

mark-restore

Restore the last cleared marks.

next

Select next image.

syntax: :next [--keep-zoom]

optional arguments:

• --keep-zoom: Keep zoom level and scroll position of the current image.

count: multiplier

nop

Do nothing.

This is useful to remove keys bound by Qt by explicitly binding them to nop.

open

Open one or more paths.

syntax: :open path [path ...]

If any path given is an image, all valid images are opened in image mode. Otherwise the first valid directory is opened. If both fails, an error is displayed.

Hint

Passing a single directory therefore changes the directory in the library, think cd.

positional arguments:

• paths: The path(s) to open.

paste-name

Paste path from clipboard to open command.

syntax: :paste-name [--primary]

optional arguments:

• --primary: Paste from primary selection.

prev

Select previous image.

syntax: :prev [--keep-zoom]

optional arguments:

• --keep-zoom: Keep zoom level and scroll position of the current image.

count: multiplier

print-stdout

Print text to the terminal.

syntax: :print-stdout text [--sep] [--end]

positional arguments:

• text: List of strings to concatenate and print

optional arguments:

• --sep: String inserted between list element, default is new line.

• --end: String appended after last element, default is new line.

quit

Quit vimiv.

rename

Rename images with a common base.

syntax: :rename path [path ...] base [--start=INDEX] [--separator=SEPARATOR] [--overwrite] [--skip-image-check]

Example::

:rename %f identifier would rename all images in the filelist to identifier_001, identifier_002, …, identifier_NNN.

positional arguments:

• paths: The path(s) to rename.

• base: Base name to use for numbering.

optional arguments:

• --start: Index to start numbering with. Default: 1.

• --separator: Separator between base and numbers. Default: ‘_’.

• --overwrite: Overwrite existing paths when renaming.

• --skip-image-check: Do not check if all renamed paths are images.

repeat-command

Repeat the last command.

count: Repeat count times.

scale

Scale the image.

syntax: :scale [--level=LEVEL]

count: If level is a float, multiply by count.

optional arguments:

• --level: The level to scale the image to.

Hint

supported levels:

• fit: Fit image to current viewport.

• fit-width: Fit image width to current viewport.

• fit-height: Fit image height to current viewport.

• overzoom: Like fit but limit to the overzoom setting.

• float: Set scale to arbitrary decimal value.

search

Start a search.

syntax: :search [--reverse]

optional arguments:

• --reverse: Search in reverse direction.

search-next

Continue search to the next match.

syntax: :search-next

count: multiplier

search-prev

Continue search to the previous match.

syntax: :search-next

count: multiplier

set

Set an option.

syntax: :set name[!] [[+|-]value]

positional arguments:

• name: Name of the setting to set. Append a ! to toggle the value of boolean settings.

• value: Value to set the setting to. Prepend with + / - to increment/decrement the value of numerical settings. If not given, set to default.

sleep

Sleep for a given number of seconds.

syntax: :sleep duration

positional arguments:

• duration: The number of seconds to sleep.

spawn

Spawn a command in a sub-shell.

syntax: :spawn command [--shell=shell --shellarg=shellarg]

positional arguments:

• command: Full command with arguments to pass to the shell.

optional arguments:

• --shell: The program to use as sub-shell. Default: sh.

• --shellarg: Argument to prepend for the shell. Default: -c.

The difference to running commands with ! is that an actual shell is involved instead of running the program directly. This means that shell, redirection etc. will work in spawn, but not with !. Nevertheless ! is recommended in general for performance and security reasons.

tag-delete

Delete an existing tag.

syntax: :tag-delete name

Warning

If you pass a tag group directory, the complete tree is deleted.

positional arguments:

• name: Name of the tag to delete.

tag-load

Load images from a tag into the current mark list.

syntax: tag-load name

Hint

You can open all marked images with :open %m.

positional arguments:

• name: Name of the tag to load.

tag-open

Open images from a tag in image mode.

syntax: tag-open name

Hint

This is equivalent to :tag-load name && open %m.

positional arguments:

• name: Name of the tag to open.

tag-write

Write marked paths to a tag.

syntax: :tag-write name

This writes all currently marked images to this tag. This allows storing a selection of marked images under a name and re-loading them in later sessions using :tag-load name. If the tag file exists, all marked paths that are not in the tag are appended to it.

Hint

It is possible to group tags into directories by dividing the name into a directory tree, e.g. :tag-write favourites/2017.

positional arguments:

• name: Name of the tag to create.

toggle

Toggle one mode.

syntax: :toggle mode.

If the mode is currently visible, leave it. Otherwise enter it.

positional arguments:

• mode: The mode to toggle (image/library/thumbnail/manipulate).

unbind

Unbind a keybinding.

syntax: :unbind keybinding [--mode=MODE]

positional arguments:

• keybinding: The keybinding to unbind.

optional arguments:

• --mode: The mode to unbind the keybinding in. Default: current.

undelete

Restore a file from the trash directory.

syntax: :undelete [basename ...]

If no basename is given, the last deleted images in this session are restored.

positional arguments:

• basenames: The basename(s) of the file in the trash directory.

version

Show a pop-up with version information.

syntax: :version [--copy]

optional arguments:

• --copy: Copy version information to clipboard instead.

welcome-to-qt

Show a pop-up with a welcome message for users coming from gtk.

Image

Overview of image commands

Command	Description
center	Center the image in the viewport.
crop	Display a widget to crop the current image.
flip	Flip the image.
goto	Select specific image in current filelist.
play-or-pause	Toggle between play and pause of animation.
reload	Reload the current image.
rescale	Rescale the original image to a new size.
resize	Resize the original image to a new size.
rotate	Rotate the image.
scroll	Scroll the image in the given direction.
scroll-edge	Scroll the image to one edge.
slideshow	Toggle slideshow.
straighten	Display a grid to straighten the current image.
undo-transformations	Undo any transformation applied to the current image.
write	Save the current image to disk.
zoom	Zoom the current widget.

center

Center the image in the viewport.

crop

Display a widget to crop the current image.

syntax: crop [--aspectratio=ASPECTRATIO]

optional arguments:

• --aspectratio: Fix the cropping to the given aspectratio. Valid options are two integers separated by : or the special keep to keep the aspectratio of the current image.

flip

Flip the image.

syntax: :flip [--vertical]

optional arguments:

• --vertical: Flip image vertically instead of horizontally.

goto

Select specific image in current filelist.

syntax: :goto index

positional arguments:

• index: Number of the image to select.

Hint

-1 is the last image.

count: Select [count]th image instead.

play-or-pause

Toggle between play and pause of animation.

reload

Reload the current image.

rescale

Rescale the original image to a new size.

syntax: :rescale dx [dy]

positional arguments:

• dx: Factor in x direction to scale the image by.

• dy: Factor in y direction to scale the image by. If not given, the aspectratio is preserved.

resize

Resize the original image to a new size.

syntax: :resize width [height]

positional arguments:

• width: Width in pixels to resize the image to.

• height: Height in pixels to resize the image to. If not given, the aspectratio is preserved.

rotate

Rotate the image.

syntax: :rotate [--counter-clockwise]

optional arguments:

• --counter-clockwise: Rotate counter clockwise.

count: multiplier

scroll

Scroll the image in the given direction.

syntax: :scroll direction

positional arguments:

• direction: The direction to scroll in (left/right/up/down).

count: multiplier

scroll-edge

Scroll the image to one edge.

syntax: :scroll-edge direction.

positional arguments:

• direction: The direction to scroll in (left/right/up/down).

slideshow

Toggle slideshow.

count: Set slideshow delay to count instead.

straighten

Display a grid to straighten the current image.

The image can then be straightened clockwise using the l, > and L keys and counter-clockwise with h, < and H. Accept the changes with <return> and reject them with <escape>.

undo-transformations

Undo any transformation applied to the current image.

write

Save the current image to disk.

syntax: :write [path].

positional arguments:

• path: Save to this path instead of the current one.

zoom

Zoom the current widget.

syntax: :zoom direction

positional arguments:

• direction: The direction to zoom in (in/out).

count: multiplier

Library

Overview of library commands

Command	Description
goto	Select specific row in current filelist.
move-view	Move the view keeping the cursor on the same position.
open-selected	Open the currently selected path.
scroll	Scroll the library in the given direction.

goto

Select specific row in current filelist.

syntax: :goto row

positional arguments:

• row: Number of the row to select.

optional arguments:

• --open-selected: Automatically open any selected image.

Hint

-1 is the last row.

count: Select [count]th element instead.

move-view

Move the view keeping the cursor on the same position.

syntax: :move-view position

positional arguments:

• position: Position to move the view to (top/center/bottom).

open-selected

Open the currently selected path.

If the path activated is an image, it is opened in image mode. If it is a directory, the library is loaded for this directory.

syntax: :open-selected [--close]

optional arguments:

• --close: Close the library if an image was selected.

scroll

Scroll the library in the given direction.

syntax: :scroll direction

The behaviour is similar to the file manager ranger.

• Scrolling right selects the current file.

• Scrolling left selects the parent directory.

• Scrolling up and down moves the cursor.

positional arguments:

• direction: The direction to scroll in (left/right/up/down/page-up/page-down/half-page-up/half-page-down).

optional arguments:

• --open-selected: Automatically open any selected image.

count: multiplier

Thumbnail

Overview of thumbnail commands

Command	Description
end-of-line	Select the last thumbnail in the current row.
first-of-line	Select the first thumbnail in the current row.
goto	Select specific thumbnail in current filelist.
move-view	Move the view keeping the cursor on the same position.
open-selected	Open the currently selected thumbnail in image mode.
scroll	Scroll to another thumbnail in the given direction.
zoom	Zoom the current widget.

end-of-line

Select the last thumbnail in the current row.

first-of-line

Select the first thumbnail in the current row.

goto

Select specific thumbnail in current filelist.

syntax: :goto index

positional arguments:

• index: Number of the thumbnail to select.

Hint

-1 is the last thumbnail.

count: Select [count]th thubnail instead.

move-view

Move the view keeping the cursor on the same position.

syntax: :move-view position

positional arguments:

• position: Position to move the view to (top/center/bottom).

open-selected

Open the currently selected thumbnail in image mode.

scroll

Scroll to another thumbnail in the given direction.

syntax: :scroll direction

positional arguments:

• direction: The direction to scroll in (left/right/up/down/page-up/page-down/half-page-up/half-page-down).

count: multiplier

zoom

Zoom the current widget.

syntax: :zoom direction

positional arguments:

• direction: The direction to zoom in (in/out).

count: multiplier

Command

Overview of command commands

Command	Description
complete	Invoke command line completion.
history	Cycle through command history.
history-substr-search	Cycle through command history with substring matching.
leave-commandline	Leave command mode.
nop	Do nothing.

complete

Invoke command line completion.

syntax: :complete [--inverse]

optional arguments:

• --inverse: Complete in inverse direction.

history

Cycle through command history.

syntax: :history direction

positional arguments:

• direction: The direction to cycle in (next/prev).

history-substr-search

Cycle through command history with substring matching.

syntax: :history-substr-search direction

positional arguments:

• direction: The direction to cycle in (next/prev).

leave-commandline

Leave command mode.

nop

Do nothing.

This is useful to remove keys bound by Qt by explicitly binding them to nop.

Manipulate

Overview of manipulate commands

Command	Description
accept	Leave manipulate accepting the applied changes.
command	Enter command mode.
decrease	Decrease the value of the current manipulation.
discard	Discard any changes and leave manipulate.
fullscreen	Toggle fullscreen mode.
goto	Set the value of the current manipulation.
help	Show help on a command or setting.
history-clear	Clear the command history.
increase	Increase the value of the current manipulation.
keybindings	Show a pop-up with keybindings information.
next	Focus the next manipulation in the current tab.
next-tab	Focus the next manipulation tab.
nop	Do nothing.
prev	Focus the previous manipulation in the current tab.
prev-tab	Focus the previous manipulation tab.
set	Set an option.

accept

Leave manipulate accepting the applied changes.

command

Enter command mode.

syntax: :command [--text=TEXT]

optional arguments:

• --text: String to append to the : prefix.

decrease

Decrease the value of the current manipulation.

syntax: :decrease value

positional arguments:

• value: The value to decrease by.

count: multiplier

discard

Discard any changes and leave manipulate.

fullscreen

Toggle fullscreen mode.

goto

Set the value of the current manipulation.

syntax: :goto value

positional arguments:

• value: Value to set the manipulation to.

count: Set the manipulation to [count] instead.

help

Show help on a command or setting.

syntax: :help topic

positional arguments:

• topic: Either a valid :command or a valid setting name.

Hint

For commands help :command is the same as command -h.

history-clear

Clear the command history.

This clears the history of all modes unless --mode is passed.

syntax: :history-clear [--mode]

optional arguments:

• --mode: Clear the history of the current mode only.

increase

Increase the value of the current manipulation.

syntax: :increase value

positional arguments:

• value: The value to increase by.

count: multiplier

keybindings

Show a pop-up with keybindings information.

syntax: :keybindings [--columns=N]

optional arguments:

• --columns: Number of columns to split the bindings in.

next

Focus the next manipulation in the current tab.

count: multiplier

next-tab

Focus the next manipulation tab.

count: multiplier

nop

Do nothing.

This is useful to remove keys bound by Qt by explicitly binding them to nop.

prev

Focus the previous manipulation in the current tab.

count: multiplier

prev-tab

Focus the previous manipulation tab.

count: multiplier

set

Set an option.

syntax: :set name[!] [[+|-]value]

positional arguments:

• name: Name of the setting to set. Append a ! to toggle the value of boolean settings.

• value: Value to set the setting to. Prepend with + / - to increment/decrement the value of numerical settings. If not given, set to default.