Command line

From Valve Developer Community
(Redirected from Command-line)
Jump to: navigation, search
Did you mean Command Line Options?

The Source SDK's command line tools are those operated with written instructions, as opposed to the clicking of buttons and browsing for files which drives GUI tools. This article will give a brief overview of how to use them.

Basics

cmd.exe icon

There are several ways to access the command line, but the simplest is the command prompt. To access it in Windows Vista or better search the start menu for cmd (type all letters). In Windows XP or older, press Windows+R, type cmd, then press Return or Enter instead.

Tip:If you're in a hurry, commands can be executed directly from the start menu search box or the Run dialogue. But don't start doing that just yet.
Tip:Copying and pasting is a bit weird in CMD. To paste, right-click and choose the menu option. To copy, right-click and choose Mark, then drag your mouse over the area you want and right-click again.

Commands

Now you're ready to submit commands. Simply type away and hit Return or Enter when you're done. Here's an example of something you might try:

"%sourcesdk%\bin\orangebox\bin\bspzip.exe"

And here is what's going on:

  1. %sourcesdk% is a special shortcut to the SDK's install folder created when you run the SDK Launcher. It's much easier than typing out C:\Program Files\Steam\steamapps\<your Steam account name>\sourcesdk\, and you'll see it a lot on this site.
    Tip:If you want, you can create a new shortcut directly to the tools folder. Look up how to create environment variables and point one towards "%sourcesdk%\bin\orangebox\bin\".
  2. The quote marks at the start and end ensure that the command isn't split into two by the space character in it. What space? The one in C:\Program Files\ of course! If there isn't a space in the path then the quotes aren't needed.
    Warning:Don't put parameters (see below) within quotes unless they actually require it. Certainly don't put them in the same set of quotes as the tool's.
  3. The remainder of the command is a bog-standard path to the BSPZIP tool that you should be familiar with from Windows.
    Tip:.exe files' extensions aren't actually needed, but are included here for clarity.

Parameters

That command will run BSPZIP, but all the program will do is print out the further commands you can give to make it actually do things.

The commands accepted by each tool vary, and are one of the things this site documents. But the pattern of usage is the same every time:

<program> <command> <argument(s)> <command> <argument(s)> ...

Notice how everything is separated by a space character; remember the quotes trick if this becomes a problem. So:

"%sourcesdk%\bin\orangebox\bin\bspzip.exe" -extract mymap.bsp contents.zip
  • -extract is a command, which tells BSPZIP what you're trying to do. Command are normally prefixed with a '-' character.
  • mymap.bsp and contents.zip are arguments, which give more details about how the command should perform its task.

Note that a command doesn't always take an argument, and that sometimes there are commands that doesn't have a keyword: you just give a value, typically a file name, and the tool does its thing.

If you examine BSPZIP's article you will see that the command above will take whatever files are embedded in the map and stick them in a .zip file somewhere on the hard drive. But where? The answer follows:

The working directory

You must pass a path to the location of every file or tool you want to work with. Except, that is, if it's in the 'working directory'. This is displayed before the cursor every time CMD is waiting for input, followed by a >, and will probably be pointing towards your user folder right now.

This means that if we type mymap.bsp or contents.zip as in the example above, BSPZIP will look for C:\Users\You\mymap.bsp and create C:\Users\You\contents.zip (assuming that's where your user folder is). That most likely isn't what you want, and to fix it you need to use the cd ('change directory') command before starting the tool itself:

cd "C:\Users\You\Documents\My mod\maps\"

That's a command followed by a parameter without a keyword, wrapped in quotes because of the space in My mod. Now BSPZIP will look for the two files in that folder, and hopefully find them there.

Alternatively you could type the full path for each file into the command, but since there are two such files in the command it's faster to cd first.

Tip:It is also possible to specify relative paths. Use .\ for the current folder and work from there: e.g. .\maps\some_subfolder\. Use ..\ for the folder above the current one: e.g. ..\ to access My mod, ..\..\ to access Documents.

The working directory is not stored between sessions: it must be set every time you open the command prompt. Typing it in all the time gets old fast, which is why we have batch files.

Batch files

Batch file icon

Commands can be written down in batch files that can then be executed at any time. To create one, save or rename any text file with the extension .cmd.

Aside from the fact that nothing is immediately executed, creating a batch file and typing straight into the command prompt are more or less the same. Type the command, hit Return, type the next. There are only two things you should know:

Pausing

The pause command will cause the CMD window that opens whenever the batch file is executed to wait for a keystroke to continue. This is vital for examining what's going on as otherwise it would close as soon as the operation had completed, which often takes only a split second. For instance:

cd "C:\Users\You\Documents\My mod\maps\"
"%sourcesdk%\bin\orangebox\bin\bspzip.exe" -extract mymap.bsp ..\contents.zip
pause

Filename substitution

In a similar manner to %sourcesdk%, the words %1 to %9 will be replaced by the path to any files that are dragged and dropped onto the batch file.

In the example being used by this article you'll have to get a little creative, since there are two values that need files but you only want to have to drag the map over. You could try something like this:

"%sourcesdk%\bin\orangebox\bin\bspzip.exe" -extract %1 %1_contents.zip

Which, if mymap.bsp is dropped onto it, will create mymap.bsp_contents.zip in the same folder. No need for cd this time, but a batch file like this won't work if it's just double-clicked on.

See also