> For the complete documentation index, see [llms.txt](https://chaoses-ib.gitbook.io/directory-opus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/command.md). # Command The **Command** object is used by a script to run Opus commands. Any command that you can run from a button or hotkey you can run from a script - a script can even run [commands added by other scripts](/directory-opus/manual/scripting/example_scripts/adding_a_new_internal_command.md). Fundamentally, using the **Command** object is similar to configuring an Opus button. You add one or more command lines to the object just the same as you add one or more command lines to a button's function. You can tell it which files and folders to act upon, and you can use the various methods and properties of the object to modify the behavior of the command. Once the object has been initialized you can use the **Run** or **RunCommand** methods to invoke the command. A **Command** object can be created by the [**DOpusFactory**](/directory-opus/manual/reference/scripting_reference/scripting_objects/dopusfactory.md)**.Command** method. By default, this object has no source, destination, files to operate on, etc. - you must use the appropriate methods to configure the command before running it. You can also retrieve a **Command** object from the [**Func**](/directory-opus/manual/reference/scripting_reference/scripting_objects/func.md)**.command** property, and in this case the source, destination, files to operate on and several other properties are pre-initialized for you. | Property Name | Return Type | Description | | ------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | deselect | *bool* | Set this property to **False** to prevent files used by this command from being deselected, and **True** to deselect them once the function is finished. Note that files will only be deselected if they came from a [**Tab**](/directory-opus/manual/reference/scripting_reference/scripting_objects/tab.md) object, and only then if the command is successful. | | dest | *object:*[**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) | Returns a [**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) object that represents the destination folder of this command. If a destination tab is set, this will be the path in the tab. You can not set this property directly - instead, use either the **SetDest** or **SetDestTab** methods to change the destination folder. | | desttab | *object:*[**Tab**](/directory-opus/manual/reference/scripting_reference/scripting_objects/tab.md) | Returns a [**Tab**](/directory-opus/manual/reference/scripting_reference/scripting_objects/tab.md) object that represents the destination tab for this command (if it has one - not all commands require a destination). You can not set this property directly - instead, use the **SetDestTab** method to change the destination tab. | | filecount | *int* | Returns the number of items in the **files** object. | | files | *object:*[**Items**](/directory-opus/manual/reference/scripting_reference/scripting_objects/items.md) | Returns a [**Items**](/directory-opus/manual/reference/scripting_reference/scripting_objects/items.md) object that represent the files and folders this command is to act upon. You can not modify this object directly - instead you can use the various methods (**ClearFiles**, **SetFiles**, **AddFile**, **RemoveFile**, etc.) to modify the list of items to act upon. | | linecount | *int* | Returns the number of instruction lines added to the command. | | progress | *object:*[**Progress**](/directory-opus/manual/reference/scripting_reference/scripting_objects/progress.md) | Returns a [**Progress**](/directory-opus/manual/reference/scripting_reference/scripting_objects/progress.md) object that you can use to display a progress indicator to the user. | | results | *object:*[**Results**](/directory-opus/manual/reference/scripting_reference/scripting_objects/results.md) | After every command that is run with this object, a **Results** object is available from this property. This provides information about the outcome of the command. | | source | *object:*[**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) | Returns a [**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) object that represents the source folder of this command. If a source tab is set, this will be the path in the tab. You can not set this property directly - instead, use either the **SetSource** or **SetSourceTab** methods to change the source folder. | | sourcetab | *object:*[**Tab**](/directory-opus/manual/reference/scripting_reference/scripting_objects/tab.md) | Returns a [**Tab**](/directory-opus/manual/reference/scripting_reference/scripting_objects/tab.md) object that represents the source tab for this command. You can not set this property directly - instead, use the **SetSourceTab** method to change the source tab. | | vars | *object*:[**Vars**](/directory-opus/manual/reference/scripting_reference/scripting_objects/vars.md) | This [**Vars**](/directory-opus/manual/reference/scripting_reference/scripting_objects/vars.md) object represents all defined variables with *command scope* (that are scoped to this function - e.g. that were set using the **@set** directive). | | Method Name | **Arguments** | Return Type | Description | | | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | AddFile |

\
or <\*\*Path:path>
or <Item:\*\*item>

| *int* |

Adds the specified item to the collection of items this command is to act upon. You can pass the item's path as either a string or a Path object, and you can also pass an Item object directly.

This method returns the total number of items in the collection.

| | | | AddFiles |

object:Items
or Vector:Item
or Vector:Path
or Vector:string
or StringSet
or UnorderedSet

| *int* |

Adds the items in the specified collection to the list of items this command is to act upon. The return value is the new number of items in the collection.

You can also pass a Vector of Item or Path objects, or full path strings, instead of a collection. Or a StringSet or UnorderedSet of full path strings.

| | | | AddFilesFromClipboard | *none* | *int* | Adds the contents of the clipboard to the collection of items this command is to act upon. This method supports both files and file paths copied to the clipboard as text. The return value is the new number of items in the collection. | | | | AddFilesFromFile |

\
\

| *int* |

Reads file paths from the contents of the specified file and adds them to the item collection. You can provide the file's path as either a string or a Path object. The file must consist of one absolute path per line.
The encoding of the file is assumed to be ANSI, unless it has a BOM (byte-order-mark) at the start, or you specify the encoding argument. If you specify the encoding this must be a string equal to one of the following: utf16be, utf16le, utf8, ansi or cp:XXXX where XXXX specifies the code page number).

The return value is the new number of items in the collection.

| | | | AddFilesFromFolder | \ | *int* | Adds the contents of the specified folder to the collection of items this command is to act upon. You can pass the folder's path as either a *string* or a [**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) object. You can also append a [wildcard pattern](/directory-opus/manual/reference/wildcard_reference/pattern_matching_syntax.md) to the path to only add files matching the specified pattern. | | | | AddLine | \ | *none* | Adds the specified instruction line to the command that this object will run. The **AddLine** method lets you build up complicated multiple line commands - add each line in turn and then run the command using the **Run** method. For a single line command it is simpler to use the **RunCommand** method. | | | | Clear | *none* | *none* | Clears all instruction lines from the command. | | | | ClearFailed | *none* | *none* | Clears the failure flags from the [**Items**](/directory-opus/manual/reference/scripting_reference/scripting_objects/items.md) collection. Any items that fail when a command is run will have their **failed** property set to **True**, and once this has happened the file will be skipped over by any subsequent commands. You can call this method to reset all the failure flags. | | | | ClearFiles | *none* | *none* | Clears the collection of items this command is to act upon. | | | | ClearModifier | \ | *none* | Clears any modifiers that have been set for this command. The supported modifiers are a subset of the full list of [command modifiers](/directory-opus/manual/reference/command_reference/command_modifier_reference.md) - see the **SetModifier** method for a list of these. You can also pass \* to clear all modifiers that have been set. | | | | CommandList |

none
or \

| *object:*[**StringSet**](/directory-opus/manual/reference/scripting_reference/scripting_objects/stringset.md) |

Returns a StringSet containing the names of all the Opus commands. You can optionally filter this set by providing one or more of the following flags as an argument to the CommandList method:

none

| *object:*[**Dialog**](/directory-opus/manual/reference/scripting_reference/scripting_objects/dialog.md) | Creates a new [**Dialog**](/directory-opus/manual/reference/scripting_reference/scripting_objects/dialog.md) object, that lets you display dialogs and popup menus. The dialog's **window** property will be automatically assigned to the source tab. | | | | | | | | | **i** | internal (built-in) commands | | | | | | **s** | script commands | | | | | | **u** | user commands | | | | | | | | | | | | | | | | | | | | Dlg | | | | | | | GetModifiers | *none* | *object:*[**Map**](/directory-opus/manual/reference/scripting_reference/scripting_objects/map.md) | Returns a \*\*[Map](/directory-opus/manual/reference/scripting_reference/scripting_objects/map.md)\*\*of the modifiers that have been set for this command (either by the **SetModifier** method, or in the case of [script add-ins](/directory-opus/manual/scripting/script_add-ins.md) any modifiers that were set on the button that invoked the script). | | | | IsSet |

\
\[\]

| *bool* | Returns **True** if the specified [**Set**](/directory-opus/manual/reference/command_reference/internal_commands/set.md) command condition is true. This is the equivalent of the **@ifset** [command modifiers.](/directory-opus/manual/reference/command_reference/command_modifier_reference.md) The optional second parameter lets you test a condition based on a command other than **Set** - for example, **IsSet("VIEWERCMD=mark", "Show")** in the viewer to test if the current image is marked. | | | | RemoveFile |

\
or <Path:path>
or <Item:item>
or \

| *int* | Removes the specified file from the [**Items**](/directory-opus/manual/reference/scripting_reference/scripting_objects/items.md) collection. You can pass the file's path as either a *string* or a [**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) object. You can also pass the [**Item**](/directory-opus/manual/reference/scripting_reference/scripting_objects/item.md) itself, or its index (starting from 0) within the collection. The return value is the new number of items in the collection. | | | | Run | *none* | *int* | Runs the command that has been built up with this object. The return value indicates whether or not the command ran successfully. Zero indicates the command could not be run or was aborted; any other number indicates the command was run for at least some files. (Note that this is not the "exit code" for external commands. For external commands it only indicates whether or not Opus launched the command. If you need the exit code of an external command, use the WScript.Shell Run or Exec methods to run the command.) You can use the **Results** property to find out more information about the results of the command, and also discover which files (if any) failed using the **failed** property of each [**Item**](/directory-opus/manual/reference/scripting_reference/scripting_objects/item.md) in the **files** collection. | | | | RunAsync | *none* | *int* | Asynchronously runs the command that has been built up with this object, without waiting for it to return. The return value indicates whether or not the command was launched successfully, but no further information about the results of the command is available. | | | | RunCommand | \ | *int* | Runs the single line command given by the *instruction* argument. Calling this method is the equivalent of adding the single line with the **AddLine** method and then calling the **Run** method. | | | | RunCommandAsync | \ | *int* | Asynchronously runs the single line command given by the *instruction* argument, without waiting for it to return. Calling this method is the equivalent of adding the single line with the **AddLine** method and then calling the **RunAsync** method. | | | | SetDest | \ | *none* | Sets the command's destination to the specified path. You can provide the path as either a *string* or a [**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) object. Calling this method clears the destination tab property from the command. | | | | SetDestTab | <[**Tab**](/directory-opus/manual/reference/scripting_reference/scripting_objects/tab.md):tab> | *none* | Sets the command's destination to the specified tab. The destination path will be initialized from the tab automatically (so you don't need to call **SetDest** as well as **SetDestTab**). | | | | SetFiles |

object:Items
or Vector:Item
or Vector:Path
or Vector:string
or StringSet
or UnorderedSet

| *none* |

Configures the command to use the files in the specified Items collection as the items the command will act upon.

You can also pass one of the other collection types, the same as with the AddFiles method.

| | | | SetModifier |

\
\

| *none* |

Turns on a modifier for this command. The supported modifiers are a subset of the full list of command modifiers:
admin, async, codepage, externalonly, leavedoswindowopen, nodeselect, noexpandenv, nofilenamequoting, nolocalizefiles, noprogress, norunbatch, resolvelinks, runmode.

Using this method is the equivalent of using the AddLine method to add the modifier to the command as an instruction; e.g. Command.SetModifier("admin") is the same as Command.AddLine("@admin"). If the modifier requires a value it is passed as the second argument, e.g. Command.SetModifier("runmode", "hide").

| | | | SetProgress | <[**Progress**](/directory-opus/manual/reference/scripting_reference/scripting_objects/progress.md):progress> | *none* | Lets you share the progress indicator from one command with another command. You can pass this method the value of **progress** property obtained from another **Command** object. | | | | SetQualifiers | \ | *none* |

This method lets you control which qualifier keys the command run by this object will consider to have been pressed when it was invoked. For example, several internal commands change their behavior when certain qualifier keys are held down - calling this method allows you to set which keys they will see.

The qualifiers argument must consist of one or more of the following strings (comma-separated): none, shift, ctrl, alt, lwin, rwin, win.

| | | | SetSource | \ | *none* | Sets the command's source to the specified path. You can provide the path as either a *string* or a [**Path**](/directory-opus/manual/reference/scripting_reference/scripting_objects/path.md) object. Calling this method clears the source tab property from the command. | | | | SetSourceTab | <[**Tab**](/directory-opus/manual/reference/scripting_reference/scripting_objects/tab.md):tab> | *none* | Sets the command's source to the specified tab. The source path will be initialized from the tab automatically (so you don't need to call **SetSource** as well as **SetSourceTab**). | | | | SetType | \ | *none* | Sets the type of function that this command will run. This is equivalent to the drop-down control in the [Advanced Command Editor](/directory-opus/manual/customize/creating_your_own_buttons/command_editor/advanced_command_editor.md). The *type* argument must be one of the following strings: **std**, **msdos**, **script**, **wsl**. Standard (**std**) is the default if the type is not specifically set. | | | | UpdateToggle | *none* | *none* | This method can be used to update the appearance of toolbar buttons that use variables to determine their labels or states. For example, a button might use [**@toggle:if**](/directory-opus/manual/reference/command_reference/command_modifier_reference.md) to set its selection state based on the existence of a *global-*, *tab-* or *Lister-scoped* variable. You would call this method if you have changed such a variable from a script to force buttons that use it to update. | | | | | | | | ----- | ---------------------------- | - | | **i** | internal (built-in) commands | | | **s** | script commands | | | **u** | user commands | | | | | | | | | | | Dlg | | |