Getting Started with Command Line Applications
Introduction
This Appligent Document Solutions software is a server application that is run from a command-line. If you are use to the Microsoft Windows or Apple Mac OS X operating system, you may not be familiar with using command-line tools. This document shows you all you need to get started.
What Is A Command-Line Application
A Command-line interface (CLI) is a user interface to a computer’s operating system or software where a user types commands to perform specific tasks. The user responds to visual prompts and receives responses back from the system or software program. Users can enter multiple commands to execute different instructions to the system or software, one command at a time. The MS-DOS Prompt application in the Windows operating system and Terminal applications in the Mac OS X/ Unix operating systems are examples of a command-line interface.
Appligent’s server software processes PDF documents as input and creates output PDF documents as the result based on commands issued on the command-line.
Windows
To run an application in Windows, you need to open a MS-DOS Command Prompt window.
In Windows NT:
- Click Start > Programs > MS-DOS Command Prompt
In Windows 2000 or XP:
- Click Start > Programs > Accessories > Command Prompt
In Windows Vista:
- Click Start > All Programs > Accessories > Command Prompt
The Command Prompt window opens.
Mac OS X
To run an application on the Macintosh, you need to open a terminal window.
- Open the Applications folder
- Open the Utilities folder
- Double-click the Terminal application
The Terminal window opens.
Unix
Go to a terminal prompt. Run the application from this window. Follow the instructions for Mac OS X when entering commands.
Some Basic Commands
At the command prompt, you type each command, and press the Enter key to execute it. The command line is completely keyboard driven. Basic navigation keys are shown below:
| Key | Action |
|---|---|
| Backspace | Delete previous character |
| right arrow | Move right one character |
| left arrow | Move left one character |
| up arrow | Recall previous command |
| Tab | File or directory name auto complete * |
| Enter | Execute command |
*Supported on Windows XP and some Unix shells
Note: You can use the mouse to select text to be copied to the clipboard. You cannot use the mouse to position the cursor or execute a command.
Running An Application On The Command-Line
Command-line applications are executed from a command prompt on Windows, Mac OS X and Unix. The following examples show executing Appligent’s free APSaveAs software (discontinued).
APSaveAs performs a full save on one or more PDF documents. This is similar to using the Save As feature in Adobe™ Acrobat™. APSaveAs tries to delete unnecessary information that has accumulated during file edits, and frequently results in a reduced file size. Options are also available for attempting further size reductions and for linearizing output to achieve more efficient Web delivery. Linearization is also known as “Fast Web View”.
The first example will show changing your directory to where the APSaveAs software is located. Next, we will use the -h command option to see a list of all the options available when using APSaveAs.
Examples will show what you will see in the Windows Command Prompt window environment followed by examples of the Mac OS X (unix) Terminal window environment.
Commands will use paths to directories and files. We recommend that you use full path names in commands to ensure that the correct files are processed and output files are written to the correct directories. Paths are indicated by using the “\” on Windows and “/” on Mac OS X and Unix. An example of a path is:
Windows
C:\directoryname\filename.ext
This shows C:\ which is the top level of Drive C on a Windows system then a directory name that is immediately under that level, and a filename of a file in that directory.
Mac OS X/Unix
/directoryname/filename.txt
On a Mac OS X/Unix system the first / indicates the top level of the system then the directory name and a filename of a file in that directory.
You can also use “relative paths” which means a path that is relative to where you are currently located on the system. To specify a relative path use the “.\” (Windows) or “./” (Mac OS X or Unix) characters to reference the current directory and below. The dot (.) refers to the current directory and dot dot (..) refers to the directory above the current directory, the “Parent” directory. You can use the dot (.) and (..) to specify a path relative to the current directory. For example: cd .. will move you up one directory level.
Windows
• To begin you must open a Command Prompt window. See Windows on page1 for instructions. The window opens to the prompt’s default directory. The command prompt will display:
Microsoft Windows XP [5.1.2600](C) Copyright 1985-2001 Microsoft Corp. C:\directory\path>
This shows you where you are. C:\ is the top level of the C drive on your system. C:\directory\path> is the current directory.
• Change directory to where APSaveAs is located:
Type cd \ then, the enter key, to go to the top level of the drive.
Note: You can also use a “\” at the beginning of a complete path to go directly there from your current location.
C:\>cd Appligent\APSaveAs
or
C:\directory\path>cd \Appligent\APSaveAs
The command prompt changes to:
C:\Appligent\APSaveAs>
The prompt now indicates the directory you are currently in.
• Listing the contents of a directory:
Use the dir command to list the contents of a directory:
C:\Appligent\APSaveAs > dir
The computer responds with a listing of all the contents of the APSaveAs directory.
Directory of C:\Appligent\APSaveAs
07/10/2008 |
02:59 PM |
<DIR> |
|
. |
07/10/2008 |
02:59 PM |
<DIR> |
|
.. |
06/19/2008 |
09:17 AM |
|
|
Appligent Product Information |
07/03/2008 |
03:34 PM |
|
576 |
apsaveas.bat |
11/09/2004 |
12:17 PM |
|
466,944 |
APSaveAsapp.exe |
06/19/2008 |
09:17 AM |
<DIR> |
|
Documentation |
06/19/2008 |
09:17 AM |
<DIR> |
|
FREE Utilities |
07/03/2008 |
03:34 PM |
<DIR> |
|
Samples |
10/31/2006 |
04:45 PM |
|
3,671 |
uninstall.log |
|
|
4 File(s) |
|
921,751 |
bytes |
|
|
6 Dir(s) |
|
176,874,373,120 |
bytes free |
There are switches available to use with the dir command. For a list of all switches, enter help dir at the prompt.
The following switches will change the way the directory is displayed on the screen as follows:
• If the directory contents fly by too fast to read, use the /p switch with the dir command. The /p switch tells DOS to display one page at a time. Press the enter key to see the next page.
C:\Appligent\APSaveAs>dir /p
• To add the contents of the subdirectories, add the /s switch after the /p. All directories and subdirectories will display one page at a time. Press the enter key to see the next page.
C:\Appligent\APSaveAs>dir /p /s
• Running APSaveAs with the -h option will display help and usage information for APSaveAs.
Note: The -h or -help option is available with all Appligent command-line applications.
C:\Appligent\APSaveAs>.\apsaveas.bat -h
The results of the command will be displayed on the screen:
Usage: apsaveas [options] inPDFFile1 [inPDFFile2...]
-c |
Reduce the amount of white space within the PDF file; similar to Acrobat 6 [default] |
-s |
Shrink ASCII85 content streams, streams with no filter and hex index arrays in colorspace |
-d <string> |
Owner password to open this document |
-o <string> |
Output PDF filename - for multiple input files, a path to an output directory |
-w |
Save the output as a linearized file |
-l <string> |
Write progress to the given log file name |
-p |
Write progress information to diagnostics |
-v |
Print version information |
-r <string> |
APSaveAs serial number (required) |
-h |
Show help |
-help |
Show help |
# Copyright 2000-2004 by Appligent, Inc. https://appligent.com
# Written by Mark Gavin
# Version 2.2, Build Date Nov 9 2004, SPDF Build Number 1110
# Registration Number APSA-WINR-0022-XXXX-XXXX-XXXX
# Serial number is valid.
• Run APSaveAs using the -p and -o options.
This example processes the input file C:\Appligent\APSaveAs\Samples\APUtilsSample. A new file named Output.pdf will be created in the C:\Appligent\APSaveAs\Samples directory.
C:\Appligent\APSaveAs>.\apsaveas.bat -p -o .\Samples\Output.pdf .\Samples\APUtilsSample.pdf
Press the enter key to execute the command.
As shown above, these options were used process the input file:
-p — displays progress information
-o — provides an output file name so the input file is not overwritten
Note: To specify a relative path, use the .\ characters to reference the current directory. We recommend that you use full path names in all scripts to ensure the correct files are processed and output files are written to the correct directories when the script runs.
The results of the command will be displayed on the screen.
Thu Jul 03 15:14:41 2008
Input file : .\Samples\APUtilsSample.pdf
Output file : .\Samples\Output.pdf
starting size= 78415 bytes
ending size= 77310 bytes
percent shrunk = 1.41%
• Run APSaveAs using the -p, -l, -c and -o options.
This example processes the input file C:\Appligent\APSaveAs\Samples\APUtilsSample. A new file named Output.pdf will be created in the C:\Appligent\APSaveAs\Samples directory and a logfile.txt will be written in the C:\Appligent\APSaveAs directory.
C:\Appligent\APSaveAs>C:\Appligent\APSaveAs\apsaveas -p -l C:\Appligent\APSaveAs\logfile.txt -c -o C:\Appligent\APSaveAs\Samples\Output.pdf C:\Appligent\APSaveAs\Samples\APUtilsSample.pdf
Press the enter key to execute the command.
As shown above, these options were used process the input file:
-p — displays progress information
-l — writes the progress information to a log file you specify
-c — reduces the amount of white space
-o — provides an output file name so the input file is not overwritten
Note: The example above shows the use of full paths to APSaveAs, the input and output files. Using full path names ensures that the correct files are processed and output files are written to the correct directories.
The results of the command will be displayed on the screen.
Thu Jul 03 16:06:43 2008
Input file : C:\Appligent\APSaveAs\Samples\APUtilsSample.pdf
Output file : C:\Appligent\APSaveAs\Samples\Output.pdf
starting size = 78415 bytes
ending size = 74994 bytes
percent shrunk = 4.36%
Mac OS X
Mac OS X is a Unix based operating system. Commands entered on Unix systems are case sensitive. When downloading software we recommend that you create an Appligent/SoftwareName folder in your Applications directory. Then copy the contents of the tar file into the Applications/Appligent/SoftwareName folder.
The following examples show the APSaveAs directory path as /Applications/Appligent/APSaveAs.
• To begin, open a terminal window. See Mac OS X on for instructions. The window will display:
Last login: (Date and time of previous login)
Welcome to Darwin!
yourcomputer:~user$
The screen will display yourcomputer which is the name of your computer, and user which is your user name. Your home directory is located at /Users/user on the system. The ~ refers to the home directory. When you change directories you will see the new directory path following yourcomputer:, as shown below.
• Change directory to where APSaveAs is located.
Use the cd command to change directories. This will show you where you are. The path to the current directory follows yourcomputer:. For example, to change to the directory that APSaveAs is located in, type:
[yourcomputer:~]user$ cd /Applications/Appligent/APSaveAs
The command prompt changes to:
[yourcomputer:Applications/Appligent/APSaveAs]user$
• Listing the contents of a directory.
Use the ls command to list the contents of a directory:
[yourcomputer:Applications/Appligent/APSaveAs]user$ ls
The computer responds with a listing of all the contents of the APSaveAs directory.
APSaveAsInstallHelpMac.pdf |
FREE_Utilities |
install.sh |
Appligent Product Info |
apsaveas |
samples |
Documentation |
apsaveasapp |
|
To see the contents of all the subdirectories at the same time, type:
[yourcomputer:Applications/Appligent/APSaveAs]user$ ls -R
The -R switch displays the contents of APSaveAs and all the subdirectories under it. Note that these switches are case sensitive. You must use a capital ‘R.’
Use the ls -l for a long, full listing of all the contents of a directory:
[yourcomputer:Applications/Appligent/APSaveAs]user$ ls -l
The computer responds with a full listing of all the contents of the APSaveAs directory.
total 1480
-rwxrwxrwx |
1 user admin |
81912 |
Jun 16 2004 |
APSaveAsInstallHelpMac.pdf |
drwxrwxrwx |
11 user admin |
374 |
Dec 15 2004 |
Appligent Product Info |
drwxrwxrwx |
5 user admin |
170 |
Dec 15 2004 |
Documentation |
drwxrwxrwx |
3 user admin |
102 |
Dec 15 2004 |
FREE_Utilities |
-rwxr-xr-x |
1 root admin |
52 |
Jun 19 09:35 |
apsaveas |
-rwxrwxrwx |
1 user admin |
659316 |
Nov 9 2004 |
apsaveasapp |
-rwxrwxrwx |
1 user admin |
10066 |
Dec 15 2004 |
install.sh |
drwxrwxrwx |
7 user admin |
238 |
Jul 7 08:55 |
samples |
The -l switch displays the contents of APSaveAs showing the permissions, owner, group, size, modification date and name.
For ease of reading, we have eliminated [yourcomputer:path] from the prompt in the following examples.
• Running APSaveAs with the -h option will display help and usage information for APSaveAs.
Note: The -h or -help option is available with all Appligent command-line applications.
user$ apsaveas -h
The results of the command will be displayed on the screen:
Usage: apsaveas [options] inPDFFile1 [inPDFFile2 ...]
-c |
Reduce the amount of white space within the PDF file; similar to Acrobat 6 ( default ) |
-s |
Shrink ASCII85 content streams, streams with no filter and hex index arrays in colorspaces |
-d <string> |
Owner password to open this document |
-o <string> |
Output PDF filename - for multiple input files, a path to an output directory |
-w |
Save the output as a linearized file |
-l <string> |
Write progress to the given log file name |
-p |
Write progress information to diagnostics |
-v |
Print version information |
-r <string> |
APSaveAs serial number ( optional ) |
-h |
Show help |
-help |
Show help |
• Run APSaveAs using the -p and -o options.
The results of the command will be displayed on the screen. A new file named Output.pdf will be created in the /Applications/Appligent/APSaveAs/Samples directory.
user$ ./apsaveas -p -o ./Samples/Output.pdf ./Samples/APUtilsSample.pdf
Press the enter key to execute the command.
As shown above, these options were used process the input file:
-p — displays progress information
-o — provides an output file name so the input file is not overwritten
Note: To specify a relative path, use the ./ characters to reference the current directory. We recommend that you use full path names in all scripts to ensure the correct files are processed and output files are written to the correct directories when the script runs.
The results of the command will be displayed on the screen.
Input file : ./Samples/APUtilsSample.pdf
Output file : ./Samples/Output.pdf
starting size = 78415 bytes
ending size = 77310 bytes
percent shrunk = 1.41%
• Run APSaveAs using the -p, -l, -c and -o options.
This example processes the input file /Appligent/APSaveAs/Samples/APUtilsSample. A new file named Output.pdf will be created in the /Appligent/APSaveAs/Samples directory and a logfile.txt will be written in the /Appligent/APSaveAs directory.
user$ /Appligent /APSaveAs/apsaveas -p -l /Appligent/APSaveAs/logfile.txt -c -o /Appligent/APSaveAs/Samples/Output.pdf /Appligent/APSaveAs/Samples/APUtilsSample.pdf
Press the enter key to execute the command.
As shown above, these options were used process the input file:
-p — displays progress information
-l — writes the progress information to a log file you specify
-c — reduces the amount of white space
-o — writes the progress information to a log file you specify
Note: The example above shows the use of full paths to APSaveAs, the input and output files. Using full path names ensures that the correct files are processed and output files are written to the correct directories.
The results of the command will be displayed on the screen.
Thu Jul 03 16:06:43 2008
Input file : /Appligent/APSaveAs/Samples/APUtilsSample.pdf
Output file : /Appligent/APSaveAs/Samples/Output.pdf
starting size = 78415 bytes
ending size = 74994 bytes
percent shrunk = 4.36%
The examples shown here for APSaveAs use general options and options that are specific to that application. All Appligent command-line server applications use a set of general options common to all applications, and have other options that are specific to the application and the functions it performs. Descriptions of the specific options are in the section on Using the “Application” in the Users Guide.
General Command-Line Options
This section details general options that are used with all Appligent command-line applications. Table 1 below shows the general options.
Note: For ease of reading we will use the term “Application” in place of a product name in the option descriptions. The terms “appname” and “appnameapp” will be used in examples of command-line calls in this section.
Command Syntax
$appname [options] input1.pdf output1.pdf
General Options
Below is a summary of the general options for Appligent command-line applications.
| Option | Parameter | Description |
|---|---|---|
| -r | RegNum | pass registration number to the Application |
| -l | logfile | write progress information to logfile |
| -p | — | provide progress messages |
| -v | — | display version information |
| -h or -help | — | display usage information |
| -i | — | perform incremental save |
| -o | outFile.pdf | save output to a new file or directory |
| -w | — | linearize the file upon save |
General Options Detailed
-r RegNum—Pass Registration Number To The Application (optional)
Use this option to supply your registration number when you call the Application from a script or another application:
$appnameapp -r XXXX-XXXX-XXXX-XXXX-XXXX-XXXX [other options]
This option is typically not necessary and is available for use in cases where the Appligent License File can not be located by the application because of runtime environment restrictions.
-l logfile—Save Messages To A Log File (optional)
Write to a text file any errors and progress messages. This option is helpful for debugging and for understanding how applications work. The -l option must be followed by a file name.
-p—Show Progress (optional)
Write progress messages to the screen, also referred to as STDOUT, the standard output of your system. This option is helpful for debugging and for understanding how an Application works.
-v—Displays Version Information (optional)
Writes the version of the Application you are running to the screen. This is important when corresponding with support@Appligent.com; in order to best understand your problem, we must know what version of the software you have.
-h or -help—Show Usage (optional)
Display all available command-line options. The Application will not do anything else if you use these options.
-o output file—Save To A New File (required)
Save the modified file as a new file. We recommend using this option so you do not overwrite your existing files.
-i—Perform Incremental Save (optional)
An incremental save appends change information to the end of the file. This is faster than a full save, but may result in a larger file.
A full save is similar to using the “Save As…” command in Adobe Acrobat. It is a save that attempts to clean up a PDF file, often reducing its size.
-w—Linearize The File Upon Save (optional)
Save the output file as a linearized document, also known as optimized. Linearization reorganizes the file to make it more efficient for web delivery using byte serving. Individual pages can be rendered before the entire document has downloaded, so the user can start reading the document sooner.
General Command Example
The following command will run an Application with a registration key. Progress will be written to logfile.txt. The output will be written to output.pdf.
$ appnameapp -p -l logfile.txt -w -o output.pdf input.pdf