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

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. http://www.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

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