# StarAdmin CLI ## Introduction With **staradmin.exe**, users can interact with Starcounter from the command-line, running different management tasks. These tasks include stopping of running applications, killing Starcounter processes, unloading and reloading databases, and more. ## Basic Use Running staradmin without arguments will display the usage message in the console. The general syntax of the staradmin tool is: ``` staradmin [options] command [] [] ``` The **options** section include options that apply either to the program itself or to the majority of the commands. Options are specified using a `--` prefix and include both flags and properties. As an example, the `--help` flag tells staradmin to write out the usage message, while the `--database=` property allow a user to specify a specific database the upcoming command is to target. Shorthand `-d=` has the same effect. The **command** tells staradmin what is to be done. Commands are usually verbs. Common commands include `stop`, `list` and `help`. Some commands support **command options**. As their name implies, these options are optional and specific for the given command. As an example, the `list` command support the `max=` property, allowing the user to limit the set of entries in a displayed list to the value ``. Finally, most commands will require or at least support some **command parameters**. The parameter will usually describe a type of object the command should operate on; examples include `stop app ` and `help list`. The first one instruct staradmin to stop an *application* by name; the second that it should display help on the *list* command. ## Getting Help To see the latest help overview, run `staradmin --help`. To find extended help on a certain command or a known topic, issue `staradmin help `, for example `staradmin help stop` to see the help for the *stop* command. ## Console Command The **console** command shows the console output from applications ``` staradmin console [] ``` Running `staradmin console` without parameters shows the console output from the default database. Running `staradmin -d=foo console` shows console output from the "foo" database. Provide a space-separated list of database names as command parameters to show output from multiple databases. For example, `staradmin console foo` shows console output from the "foo" database. `staradmin console foo bar baz` shows console output from the "foo", "bar" and "baz" databases. ## Delete Command The **delete** command deletes various types of objects, e.g. databases. Usage: ``` staradmin delete [--force] [--failmissing] ``` Example: delete database To create a user-specified database use ```bash C:\>staradmin --database=NewDbName delete db ``` ### Command Options The delete command supports the `--force` flag. This flag tell staradmin you don't want to confirm the requested delete, which otherwise is the default in case you are deleting some sensitive artifact such as a database. Use this flag with care, there is no going back. ``` staradmin -d=foo delete --force db ``` The `--failmissing` flag toogle how staradmin behaves when the artifact you want to delete is not found. By default, such case is treated as a successful operation. With this flag applied, `staradmin` will instead issue an error. ``` staradmin -d=nonExisting delete --failmissing db ScErrDatabaseNotFound (SCERR10002): ScErrDatabaseNotFound (SCERR10002): A database with the specified name was not found. ``` ### Object Types The delete command supports the following type of objects to be deleted. * **Databases**. Usage: `staradmin -d=default delete db`. Deletes a database. ## Kill Command The **kill** command kills processes relating to Starcounter. Usage: ``` staradmin kill ``` Use `all` as the command parameter to target killing all processes relating to Starcounter on the current machine. Use this option with care and make sure no mission-critical processes are running. ## List Command The **list** command provides viewing of lists. It takes the general form: ``` staradmin list ``` where *type* will indicate the kind of list you want to see. To see a list of databases, use the **db** type; to see a list of all running applications, use **app**. ### Command Options The list command supports the `max=` property. By using this property, you tell staradmin not to list more entries than the value of ``. ``` staradmin list --max=10 app ``` *Lists running applications, limiting the result to a maximum of 10* ### Object Types The list command supports the following type of objects to be listed. * **Databases**. Usage: `staradmin list db`. List all databases part of the current installation, even those that are not running. * **Applications**. Usage: `staradmin list apps`. List all applications currently running, including information on the database they are running in. * **Logs**. Usage: `staradmin list log`. Shows the content of the server error log. See more usage on the [Error log](/2.3.1/guides/working-with-starcounter/error-log.md) page. ## New Command The **new** command allows creation of new artifacts. It takes the general form: ``` staradmin new ``` where *type* specifies the kind of artifact to create. To create a database, use the **db** type; for applications, use **app**. **Example: create database** To create a user-specified database use ```bash C:\>staradmin new db foo ``` ### Object Types The new command allow the following type of artifacts to be created: * **Databases**. Usage: `staradmin new db foo`. Creates a new database named "foo". * **Applications**. Usage: `staradmin new app`. Creates a new application source code file, normally "app.cs". ### Set Configuration Options on Creation All the available configuration options in the underlying REST JSON representation can be set from the command line. These are: * `Uri` * `DataDirectory` * `TempDirectory` * `DefaultUserHttpPort` * `FirstObjectID` * `LastObjectID` The options are specified on the creation of the database using this syntax: ``` staradmin new db DataDirectory=C:\Users\Per\Foo DefaultUserHttpPort=1234 Uri=http://example.com/api/databases/foo/configuration" ``` ## Reload Command The **reload** command reloads data into a data source, usually a database. Usage: ``` staradmin reload [source] [--file=] ``` If no *source* is given, `db` is used as the default. ### Object Types * **Databases**. Usage: `staradmin reload db`. Reloads a database. ### Command Options The reload command supports the `--file=` option. The filename is resolved to the same directory from which the command runs. If the file option is omitted, the default file is used. ``` staradmin -d=bar reload db --file=data.sql ``` *Reloads the "data.sql" file into the "bar" database.* ## Start Command The **start** command is used to start processes. It takes the general form: ``` staradmin start ``` where *type* specifies what should be started. Use `staradmin start db` to start the default database; use `staradmin start server` to start the Starcounter server. Example: start database To start a user-specified database use ```bash C:\>staradmin --database=UserDbName start db ``` To start the application with .exe extension on a specified database use: ```bash C:\[path to your application]>star --database=newdb YourApplicationName.exe ``` To find out more about how to start and stop applications read this article.\ The console output does not go to the console, but directed to a server side memory buffer and it is possible to view it from the Administrator Web UI. **NOTE**: Starting databases or the server like this is not the normal scenario. Instead, Starcounter employs a design where processes are started on demand. When starting applications, using `star ` or from within Visual Studio, doing "Start" on a **Starcounter Application project**, these processes are started for you automatically (if not already running). *Starting the "foo" database* ``` staradmin -d=foo start db Starting foo (started, code host PID: 6048) ``` ### Object Types The start command support starting the following types. * **Databases**. Usage: `staradmin start db`. Starting the default database, including all its support processes. * **The server**. Usage: `staradmin start server`. Starts the Starcounter server. ## Stop Command The **stop** command is used to stop running processes or applications. It takes the general form: ``` staradmin stop [reference] ``` where *type* will indicate the type of the given reference. As an example, to stop an application with the name *foo*, use `staradmin stop app foo`. To stop a database named *bar*, use `staradmin -d=bar stop db`. To stop the default database, use `staradmin stop db`. Example: stop database To start a user-specified database use ```bash C:\>staradmin --database=UserDbName stop db ``` ### Object Types The stop command supports stopping the following types. * **Databases**. Usage: `staradmin stop db`. Stops the default database, including all its support processes, effectively freeing all database memory. * **Applications**. Usage: `staradmin stop app [name]`. Stops an application by name. The `-d` option can be used to tell staradmin in what database look for it; if not given, the default database is assumed. * **Hosts**. Usage: `staradmin stop host`. Stops the code host of the default database. Support processes stay resident, meaning that database memory is not freed. ## Unload Command The **unload** command unloads data from a data source, usually a database. Usage: ``` staradmin unload [source] [--file=] ``` If no *source* is given, `db` is used as the default. ### Object types * **Databases**. Usage: `staradmin unload db`. Unloads a database. ### Command Options The unload command supports the `--file=` option. The filename is resolved to the same directory from which the command runs. If the file option is omitted, the default file is used. ``` staradmin -d=bar unload db --file=data.sql ``` *Unloads the "bar" database into the "data.sql" file.* The `--allowPartial` option unloads the database, allowing the unload to be partial. Usage: `staradmin unload db --allowPartial`. The `--shiftKey` option makes every key being unloaded increase with the given number. ``` staradmin unload db --shiftKey=99999 ``` *Makes every key being unloaded increase by 99999.* ## Exceptions ### ScErrHandlerAlreadyRegistered (SCERR13003) This exception is thrown when two identical handlers are registered on the same port. A common way to hit this is by running two databases where both ports are set to 8080, which is the default port. In its simplest form, it looks like this: ``` > staradmin new db default Created (Name=default) > staradmin new db another Created (Name=another) > staradmin start db default Starting default (started, code host PID: 9300) > staradmin start db another System.Exception: ScErrHandlerAlreadyRegistered (SCERR13003): This handler has already been registered. Can't register URI handler "GET /sc/htmlmerger?{?}" on port 8080. This handler is already registered. ``` The solution is to start the databases on different ports: ``` > staradmin new db default Created (Name=default) > staradmin new db another DefaultUserHttpPort=5000 Created (Name=another) ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.starcounter.io/2.3.1/guides/working-with-starcounter/staradmin-cli.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.