# tg-admin command line tool reference

The tg-admin command line tool provides commands for working with TurboGears projects. You can get a list of the available commands by running:

tg-admin

The basic syntax is:

tg-admin <command> [options]

For most commands, if you add the "-h" or "--help" argument, you'll find a reference to the options for that command.

## quickstart — create a new project

The quickstart command will give you a new project skeleton so that you can be up and running without wondering where to put things. The quickstart command needs a couple of options and can either get them from the command line or prompt you for them.

The options available for quickstart are:

    -n NAME, --name=NAME  project name
    -p PACKAGE, --package=PACKAGE
                          package name for the code
    --dry-run             dry run (don't actually do anything)

Most people will just let quickstart prompt them for the name and the package.

The name of the project is the friendly name that you want to appear on PyPI (if you're releasing it), and it's also the name that will be used for the egg (if you package it up that way).

The package name is the filesystem- and Python-friendly version of the project's name. Since Python package names are generally lower case, the package name should be lowercase as well. If you don't specify a package name on the command line, quickstart will guess at a suitable name based on the project's name.

If you use the dry-run option, quickstart will tell you about the files and directories it would have created without actually creating them.

## shell — manipulate your database with ease

The tg-admin shell command will give you a Python interactive shell, just like when you type "python" from the command line. But, unlike a default "python" command, this shell is prepopulated everything in your model.py file and with your database configuration loaded. This makes it really easy to interactively manipulate your database.

Let's say you have a class in model.py called "Person". If you know the ID of a person you want to update, you can just do something like this:

    p = Person.get(5)
    p.name = "Fred"

SQLObject generally defaults to running in autoCommit mode. This means that the p.name update is automatically saved to the database. If you want to do multiple updates in a single transaction, you can use the "hub" that is defined in the model.py file:

    hub.begin()
    p = Person.get(5)
    p.name = "Fred"
    hub.commit()
    hub.end()

The tg-admin shell command does not have any command line parameters.

## sql — wrapper for sqlobject-admin

SQLObject includes a utility called sqlobject-admin. sqlobject-admin includes a number of handy features, including a command to create a database and another for recording a checkpoint to keep track of database changes.

Running "tg-admin sql" is equivalent to sqlobject-admin, but the tg-admin sql command will pass a command line parameter specifying the database to use (as pulled from the configuration file). sqlobject-admin also automatically knows where your model objects are stored, because of metadata put into Project.egg-info/sqlobject.txt when you run quickstart.

The tg-admin sql wrapper makes it possible to create your database just by running "tg-admin sql create".

Beyond these default parameters, tg-admin sql just wraps sqlobject-admin. For further information about the commands and options available there, look at the documentation for sqlobject-admin itself.