If you, like me, are an old-time Unix command-line fanatic now doing iOS development, you've probably wondered if you can build an iPhone app from scratch, entirely outside of XCode. After all, Mac OS/X is a.nix, and all the familiar tools — Make, cc, ld — are all there. But for older versions of Mac OS X, and because app bundles aren't designed to be passed command line arguments, the conventional mechanism is to use Apple Events for files like here for Cocoa apps or here for Carbon apps. You could also probably do something kludgey by passing parameters in using environment variables.

Installing Flask installs the flask script, a Click command lineinterface, in your virtualenv. Executed from the terminal, this script givesaccess to built-in, extension, and application-defined commands. The --helpoption will give more information about any commands and options.

Application Discovery¶

The flask command is installed by Flask, not your application; it must betold where to find your application in order to use it. The FLASK_APPenvironment variable is used to specify how to load the application.

Unix Bash (Linux, Mac, etc.):

Windows CMD:

Windows PowerShell:

While FLASK_APP supports a variety of options for specifying yourapplication, most use cases should be simple. Here are the typical values:

The file wsgi.py is imported, automatically detecting an app(app). This provides an easy way to create an app from a factory withextra arguments.

The name is imported, automatically detecting an app (app) or factory(create_app).

FLASK_APP has three parts: an optional path that sets the current workingdirectory, a Python file or dotted import path, and an optional variablename of the instance or factory. If the name is a factory, it can optionallybe followed by arguments in parentheses. The following values demonstrate theseparts:

Sets the current working directory to src then imports hello.

Imports the path hello.web.

Uses the app2 Flask instance in hello.

The create_app factory in hello is called with the string 'dev'as the argument.

If FLASK_APP is not set, the command will try to import “app” or“wsgi” (as a “.py” file, or package) and try to detect an applicationinstance or factory.

Within the given import, the command looks for an application instance namedapp or application, then any application instance. If no instance isfound, the command looks for a factory function named create_app ormake_app that returns an instance.

When calling an application factory, if the factory takes an argument namedscript_info, then the ScriptInfo instance is passed as akeyword argument. If the application factory takes only one argument and noparentheses follow the factory name, the ScriptInfo instanceis passed as a positional argument. If parentheses follow the factory name,their contents are parsed as Python literals and passes as arguments to thefunction. This means that strings must still be in quotes.

Run the Development Server¶

The run command will start the development server. Itreplaces the Flask.run() method in most cases.

Warning

Do not use this command to run your application in production.Only use the development server during development. The development serveris provided for convenience, but is not designed to be particularly secure,stable, or efficient. See Deployment Options for how to run in production.

Mac Command Line

Open a Shell¶

To explore the data in your application, you can start an interactive Pythonshell with the shell command. An applicationcontext will be active, and the app instance will be imported.

Use shell_context_processor() to add other automatic imports.

Environments¶

The environment in which the Flask app runs is set by theFLASK_ENV environment variable. If not set it defaults toproduction. The other recognized environment is development.Flask and extensions may choose to enable behaviors based on theenvironment.

If the env is set to development, the flask command will enabledebug mode and flaskrun will enable the interactive debugger andreloader.

Watch Extra Files with the Reloader¶

When using development mode, the reloader will trigger whenever yourPython code or imported modules change. The reloader can watchadditional files with the --extra-files option, or theFLASK_RUN_EXTRA_FILES environment variable. Multiple paths areseparated with :, or ; on Windows.

Debug Mode¶

Debug mode will be enabled when FLASK_ENV is development,as described above. If you want to control debug mode separately, useFLASK_DEBUG. The value 1 enables it, 0 disables it.

Environment Variables From dotenv¶

Rather than setting FLASK_APP each time you open a new terminal, you canuse Flask’s dotenv support to set environment variables automatically.

If python-dotenv is installed, running the flask command will setenvironment variables defined in the files .env and .flaskenv.This can be used to avoid having to set FLASK_APP manually every time youopen a new terminal, and to set configuration using environment variablessimilar to how some deployment services work.

Variables set on the command line are used over those set in .env,which are used over those set in .flaskenv. .flaskenv should beused for public variables, such as FLASK_APP, while .env should notbe committed to your repository so that it can set private variables.

Directories are scanned upwards from the directory you call flaskfrom to locate the files. The current working directory will be set to thelocation of the file, with the assumption that that is the top level projectdirectory.

The files are only loaded by the flask command or callingrun(). If you would like to load these files when running inproduction, you should call load_dotenv() manually.

Setting Command Options¶

Click is configured to load default values for command options fromenvironment variables. The variables use the patternFLASK_COMMAND_OPTION. For example, to set the port for the runcommand, instead of flaskrun--port8000:

These can be added to the .flaskenv file just like FLASK_APP tocontrol default command options.

Disable dotenv¶

The flask command will show a message if it detects dotenv files butpython-dotenv is not installed.

You can tell Flask not to load dotenv files even when python-dotenv isinstalled by setting the FLASK_SKIP_DOTENV environment variable.This can be useful if you want to load them manually, or if you’re usinga project runner that loads them already. Keep in mind that theenvironment variables must be set before the app loads or it won’tconfigure as expected.

Environment Variables From virtualenv¶

If you do not want to install dotenv support, you can still set environmentvariables by adding them to the end of the virtualenv’s activatescript. Activating the virtualenv will set the variables.

Unix Bash, venv/bin/activate:

Windows CMD, venvScriptsactivate.bat:

It is preferred to use dotenv support over this, since .flaskenv can becommitted to the repository so that it works automatically wherever the projectis checked out.

Custom Commands¶

The flask command is implemented using Click. See that project’sdocumentation for full information about writing commands.

This example adds the command create-user that takes the argumentname.

This example adds the same command, but as usercreate, a command in agroup. This is useful if you want to organize multiple related commands.

See Testing CLI Commands for an overview of how to test your customcommands.

Registering Commands with Blueprints¶

If your application uses blueprints, you can optionally register CLIcommands directly onto them. When your blueprint is registered onto yourapplication, the associated commands will be available to the flaskcommand. By default, those commands will be nested in a group matchingthe name of the blueprint.

You can alter the group name by specifying the cli_group parameterwhen creating the Blueprint object, or later withapp.register_blueprint(bp,cli_group='...').The following are equivalent:

Specifying cli_group=None will remove the nesting and merge thecommands directly to the application’s level:

Application Context¶

Commands added using the Flask app’s clicommand() decorator will be executed with an applicationcontext pushed, so your command and extensions have access to the app and itsconfiguration. If you create a command using the Click command()decorator instead of the Flask decorator, you can usewith_appcontext() to get the same behavior.

If you’re sure a command doesn’t need the context, you can disable it:

Plugins¶

Flask will automatically load commands specified in the flask.commandsentry point. This is useful for extensions that want to add commands whenthey are installed. Entry points are specified in setup.py

Inside flask_my_extension/commands.py you can then export a Clickobject:

Once that package is installed in the same virtualenv as your Flask project,you can run flaskmy-command to invoke the command.

Custom Scripts¶

When you are using the app factory pattern, it may be more convenient to defineyour own Click script. Instead of using FLASK_APP and letting Flask loadyour application, you can create your own Click object and export it as aconsole script entry point.

Create an instance of FlaskGroup and pass it the factory:

Define the entry point in setup.py:

Install the application in the virtualenv in editable mode and the customscript is available. Note that you don’t need to set FLASK_APP.

Errors in Custom Scripts

When using a custom script, if you introduce an error in yourmodule-level code, the reloader will fail because it can no longerload the entry point.

The flask command, being separate from your code, does not havethis issue and is recommended in most cases.

PyCharm Integration¶

PyCharm Professional provides a special Flask run configuration. Forthe Community Edition, we need to configure it to call the flaskrunCLI command with the correct environment variables. These instructionsshould be similar for any other IDE you might want to use.

In PyCharm, with your project open, click on Run from the menu bar andgo to Edit Configurations. You’ll be greeted by a screen similar tothis:

There’s quite a few options to change, but once we’ve done it for onecommand, we can easily copy the entire configuration and make a singletweak to give us access to other commands, including any custom ones youmay implement yourself.

Mac Running App From Command Line Command

Click the + (Add New Configuration) button and select Python. Givethe configuration a name such as “flask run”. For the flaskruncommand, check “Single instance only” since you can’t run the servermore than once at the same time.

Select Module name from the dropdown (A) then input flask.

The Parameters field (B) is set to the CLI command to execute(with any arguments). In this example we use run, which will runthe development server.

You can skip this next step if you’re using Environment Variables From dotenv. We need toadd an environment variable (C) to identify our application. Clickon the browse button and add an entry with FLASK_APP on the left andthe Python import or file on the right (hello for example). Add anentry with FLASK_ENV and set it to development.

Mac Run Application From Command Line

Next we need to set the working directory (D) to be the folder whereour application resides.

If you have installed your project as a package in your virtualenv, youmay untick the PYTHONPATH options (E). This will more accuratelymatch how you deploy the app later.

Click Apply to save the configuration, or OK to save and close thewindow. Select the configuration in the main PyCharm window and clickthe play button next to it to run the server.

Now that we have a configuration which runs flaskrun from withinPyCharm, we can copy that configuration and alter the Script argumentto run a different CLI command, e.g. flaskshell.

Historically, the command line interface provided a way to manipulate a computer over simple, text-based connections. In the modern era, in spite of the ability to transmit graphical user interfaces over the Internet, the command line remains a powerful tool for performing certain types of tasks.

As described previously in Before You Begin, most users interact with a command-line environment using the Terminal application, though you may also use a remote connection method such as secure shell (SSH). Each Terminal window or SSH connection provides access to the input and output of a shell process. A shell is a special command-line tool that is designed specifically to provide text-based interactive control over other command-line tools.

In addition to running individual tools, most shells provide some means of combining multiple tools into structured programs, called shell scripts (the subject of this book).

Different shells feature slightly different capabilities and scripting syntax. Although you can use any shell of your choice, the examples in this book assume that you are using the standard OS X shell. The standard shell is bash if you are running OS X v10.3 or later and tcsh if you are running an earlier version of the operating system.

The following sections provide some basic information and tips about using the command-line interface more effectively; they are not intended as an exhaustive reference for using the shell environments.

Note: This appendix was originally part of Mac Technology Overview.

Basic Shell Concepts

Before you start working in any shell environment, there are some basic features of shell scripting that you should understand. Some of these features are specific to OS X, but most are common to all platforms that support shell scripting.

Running Your First Command-Line Tool

In general, you run command-line tools that OS X provides by typing the name of the tool. (The syntax for running tools that you’ve added is described later in this appendix.)

For example, if you run the ls command, by default, it lists the files in your home directory. To run this command, type ls and press Return.

Most tools also can take a number of flags (sometimes called switches). For example, you can get a “long” file listing (with additional information about every file) by typing ls -l and pressing Return. The -l flag tells the ls command to change its default behavior.

Similarly, most tools take arguments. For example, to show a long listing of the files on your OS X desktop, type ls -l Desktop and press Return. In that command, the word Desktop is an argument that is the name of the folder that contains the contents of your OS X desktop.

In addition, some tools have flags that take flag-specific arguments in addition to the main arguments to the tool as a whole.

Specifying Files and Directories

Most commands in the shell operate on files and directories, the locations of which are identified by paths. The directory names that make up a path are separated by forward-slash characters. For example, the Terminal program is in the Utilities folder within the Applications folder at the top level of your hard drive. Its path is /Applications/Utilities/Terminal.app.

The shell (along with, for that matter, all other UNIX applications and tools) also has a notion of a current working directory. When you specify a filename or path that does not start with a slash, that path is assumed to be relative to this directory. For example, if you type cat foo, the cat command prints the contents of the file foo in the current directory. You can change the current directory using the cd command.

Finally, the shell supports a number of directory names that have a special meaning.

Table A-1 lists some of the standard shortcuts used to represent specific directories in the system. Because they are based on context, these shortcuts eliminate the need to type full paths in many situations.

File and directory names traditionally include only letters, numbers, hyphens, the underscore character (_), and often a period (.) followed by a file extension that indicates the type of file (.txt, for example). Most other characters, including space characters, should be avoided because they have special meaning to the shell.

Although some OS X file systems permit the use of these other characters, including spaces, you must do one of the following:

• “Escape” the character—put a backslash character () immediately before the character in the path.

• Add single or double quotation marks around the path or the portion that contains the offending characters.

For example, the path name My Disk can be written as 'My Disk', 'My Disk', or My Disk.

Single quotes are safer than double quotes because the shell does not do any interpretation of the contents of a single-quoted string. However, double quotes are less likely to appear in a filename, making them slightly easier to use. When in doubt, use a backslash before the character in question, or two backslashes to represent a literal backslash.

For more detailed information, see Quoting Special Characters in Flow Control, Expansion, and Parsing.

Accessing Files on Additional Volumes

On a typical UNIX system, the storage provided by local disk drives is presented as a single tree of files descending from a single root directory. This differs from the way the Finder presents local disk drives, which is as one or more volumes, with each volume acting as the root of its own directory hierarchy. To satisfy both worlds, OS X includes a hidden directory, Volumes, at the root of the local file system. This directory contains all of the volumes attached to the local computer.

To access the contents of other local (and many network) volumes, you prefix the volume-relative path with /Volumes/ followed by the volume name. For example, to access the Applications directory on a volume named MacOSX, you would use the path /Volumes/MacOSX/Applications.

Note: To access files on the boot volume, you are not required to add volume information, since the root directory of the boot volume is /. Including the volume information still works, though, so if you are interacting with the shell from an application that is volume-aware, you may want to add it, if only to be consistent with the way you access other volumes. You must include the volume information for all volumes other than the boot volume.

Input And Output

Most tools take text input from the user and print text out to the user’s screen. They do so using three standard file descriptors, which are created by the shell and are inherited by the program automatically. These standard file descriptors are listed in Table A-2.

To learn more about working with these descriptors, including redirecting the output of one tool to the input of another, read Shell Input and Output.

Terminating Programs

To terminate the currently running program from the command line, press Control-C. This keyboard shortcut sends an abort (ABRT) signal to the currently running process. In most cases this causes the process to terminate, although some tools may install signal handlers to trap this signal and respond differently. (See Trapping Signals in Advanced Techniques for details.)

In addition, you can terminate most scripts and command-line tools by closing a Terminal window or SSH connection. This sends a hangup (HUP) signal to the shell, which it then passes on to the currently running program. If you want a program to continue running after you log out, you should run it using the nohup command, which catches that signal and does not pass it on to whatever command it invokes.

Frequently Used Commands

Shell scripting involves a mixture of built-in shell commands and standard programs that run in all shells. Although most shells offer the same basic set of commands, there are often variations in the syntax and behavior of those commands. In addition to the shell commands, OS X also provides a set of standard programs that run in all shells.

Table A-3 lists some commands that are commonly used interactively in the shell. Most of the items in this table are not specific to any given shell. For syntax and usage information for each command, see the corresponding man page. For a more in-depth list of commands and their accompanying documentation, see OS X Man Pages.

Environment Variables

Some programs require the use of environment variables for their execution. Environment variables are variables inherited by all programs executed in the shell’s context. The shell itself uses environment variables to store information such as the name of the current user, the name of the host computer, and the paths to any executable programs. You can also create environment variables and use them to control the behavior of your program without modifying the program itself. For example, you might use an environment variable to tell your program to print debug information to the console.

To set the value of an environment variable, you use the appropriate shell command to associate a variable name with a value. For example, to set the environment variable MYFUNCTION to the value MyGetData in the global shell environment you would type the following command in a Terminal window:

When you launch an application from a shell, the application inherits much of its parent shell’s environment, including any exported environment variables. This form of inheritance can be a useful way to configure the application dynamically. For example, your application can check for the presence (or value) of an environment variable and change its behavior accordingly. Different shells support different semantics for exporting environment variables, so see the man page for your preferred shell for further information.

Child processes of a shell inherit a copy of the environment of that shell. Shells do not share their environments with one another. Thus, variables you set in one Terminal window are not set in other Terminal windows. Once you close a Terminal window, any variables you set in that window are gone.

If you want the value of a variable to persist between sessions and in all Terminal windows, you must either add it to a login script or add it to your environment property list. See Before You Begin for details.

Similarly, environment variables set by tools or subshells are lost when those tools or subshells exit.

Running User-Added Commands

As mentioned previously, you can run most tools by typing their name. This is because those tools are located in specific directories that the shell searches when you type the name of a command. The shell uses the PATH environment variable to control where it searches for these tools. It contains a colon-delimited list of paths to search—/usr/bin:/bin:/usr/sbin:/sbin, for example.

If a tool is in any other directory, you must provide a path for the program to tell it where to find that tool. (For security reasons, when writing scripts, you should always specify a complete, absolute path.)

For security reasons, the current working directory is not part of the default search path (PATH), and should not be added to it. If it were, then another user on a multi-user system could trick you into running a command by adding a malicious tool with the same name as one you would typically run (such as the ls command) or a common misspelling thereof.

For this reason, if you need to run a tool in the current working directory, you must explicitly specify its path, either as an absolute path (starting from /) or as a relative path starting with a directory name (which can be the . directory). For example, to run the MyCommandLineProgram tool in the current directory, you could type ./MyCommandLineProgram and press Return.

With the aforementioned security caveats in mind, you can add new parts (temporarily) to the value of the PATH environment variable by doing the following:

Mac Running App From Command Line Download

If you want the additional path components to persist between sessions and in all Terminal windows, you must either add it to a login script or add it to your environment property list. See Before You Begin for details.

Running Applications

To launch an application, you can generally either:

• Use the open command.

• Run the application binary itself.

  Type the pathname of the executable file inside the package.

Note: As a general rule, if you launch a GUI application from a script, you should run that script only within Terminal or another GUI application. You cannot necessarily launch an GUI application when logged in remotely (using SSH, for example). In general, doing so is possible only if you are also logged in using the OS X GUI, and in some versions of OS X, it is disallowed entirely.

Learning About Other Commands

At the command-line level, most documentation comes in the form of man pages (short for manual). Man pages provide reference information for many shell commands, programs, and POSIX-level concepts. The manual page manpages describes the organization of manual, and the format and syntax of individual man pages.

To access a man page, type the man command followed by the name of the thing you want to look up. For example, to look up information about the bash shell, you would type man bash. The man pages are also included in the OS X Developer Library (OS X Man Pages).

You can also search the manual pages by keyword using the apropos command.

Note: Not all commands and programs have man pages. For a list of available man pages, look in the /usr/share/man directory or see OS X Man Pages in the OS X Developer Library.

Most shells have a command or man page that displays the list of commands that are built into the shell (builtins). Table A-4 lists the available shells in OS X along with the ways you can access the list of builtins for the shell.

Mac Os X Run App From Command Line

Copyright © 2003, 2014 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2014-03-10