# star tool The `star` tool is a cross-platform command-line tool, distributed as a stand-alone console application, used to manage Starcounter databases and applications. By using the `star` tool, you can – for example – create, modify, delete and query Starcounter databases, as well as import and export data from compatible 3:rd party data sources. The easiest way to explore the features of the `star` tool is to use it, in particular with the `--help` option, which prints help information about available commands and options. In this article, we will provide a reference for the available commands and describe some common use cases. ## Distribution The Windows and Linux versions of the tool are downloaded together with the main [Starcounter binaries](/undefined.md#installation). For Linux operating systems, make sure to also install the prerequisites listed at the [installation page](/undefined.md#installation) and grant execution permissions (`chmod -R u+x /path/to/star/tool/folder`). ## Usage The `star` tool is a console application with a command-line interface, and we interact with it using commands, options and arguments. The global command pattern is: ``` star [options] [command] ``` Specific commands may have different sub-patterns, which are defined in their respective sections below. The option `--help` is defined for each command, and can be used to print details on available options and sub-commands. In examples below, Windows-style directory paths are used. On Linux operating systems, the `star` tool expects Linux-style paths. ### Commands The available commands can be split into four categories: * [Database management commands](/star-tool.md#database-management), used for creating and starting databases. * [Import and export commands](/star-tool.md#import-and-export), used for importing and exporting data to or from SQLite database files. * [Information commands](/star-tool.md#information), e.g. printing all tables or listing all indexes of a given table. * [SQL REPL](/star-tool.md#sql-repl), used for executing DML and DDL statements manipulating the database schema and data. #### Database management **new** ``` star new [options] ``` The `new` command creates a new database at the absolute or relative path provided in the `` argument. If the directory referenced by the path does not exist, it will be created. To create a new database at the path `C:\databases\mydb`, we run: ``` star new C:\databases\mydb ``` **start** ``` star start [options] ``` The `start` command starts the database referenced by the absolute or relative path given in the `` argument. To start an existing database located at `C:\databases\mydb`, we run: ``` star start C:\databases\mydb ``` #### Import and export **reload** ``` star reload [options] ``` The `reload` command takes data from an SQLite database file referenced by the absolute or relative path in the `` argument and imports that data into the database referenced by the absolute or relative path given in the `` argument. To load data from an SQLite database file named `myDatabase.sqlite3` located in `C:\databases` into an existing database located at `C:\databases\mydb`, we run: ``` star reload C:\databases\mydb C:\databases\myDatabase.sqlite3 ``` *Note: only files created with the `unload` command can be reloaded.* **unload** ``` star unload [options] ``` The `unload` command selects the SQLite database file at the path given in the `` argument, or creates one if it doesn't exists, and then takes data from a database referenced by the absolute or relative path given in the `` argument and imports that data into the created SQLite database. To load data from an existing database located at `C:\databases\mydb` into a new SQLite database file named `myDatabase.sqlite3` at `C:\databases`, we run: ``` star unload C:\databases\mydb C:\databases\myDatabase.sqlite3 ``` #### Information **list** ``` star list [options] [command] ``` The `list` command is used together with one of the following sub-commands to list ranges of entities in a database: **list table** ``` star list table [options] ``` The `list table` sub-command lists all tables in the database referenced by the absolute or relative path given in the `` argument. The following options are available to configure the output of the command: | Option | Short form | Description | | ---------- | ---------- | ---------------------------------------------------------------------------------------- | | `--user` | `-u` | Includes user tables in the output. | | `--system` | `-s` | Includes system tables in the output. | | `--format` | `-f` | Lets you configure the formatting of the output by providing one or more format options. | Formatting options: * `t` – Include the name of the table to list. * `b` – Include the name of the base table (if inherited) of the table to list. To list all tables of an existing database located at `C:\databases\mydb`, including only user tables and displaying both the name of the table and the name of its base table (if any), we run: ``` star list table -u -f tb C:\databases\mydb ``` **list index** ``` star list index [options] ``` The `list index` sub-command lists all indexes in a table, the name of which is specified by the `
` argument, in the database referenced by the absolute or relative path given in the `` argument. The following options are available to configure the output of the commmand: | Option | Short form | Description | | ------------- | ---------- | -------------------------------------------------------------------------------------------- | | `--user` | `-u` | Includes user indexes in the output. | | `--system` | `-s` | Includes system indexes in the output. | | `--inherited` | `-i` | Includes the indexes of base tables in the output. | | `--format` | `-f` | Lets you configure the formatting of the output by providing one or more formatting options. | Formatting options: * `i` – Include the name of the index to list. * `t` – Include the name of the table of the index. * `u` – Include whether or not the index is unique. To list all indexes of the table `MyApp.Superhero`, of an existing database located at `C:\databases\mydb`, including both user indexes and system indexes and both the name of the index and whether it's unique, we run: ``` star list index -u -s -f iu C:\databases\mydb MyApp.Superhero ``` **info** ``` star info [options] [command] ``` The `info` command is used together with one of the following sub-commands to print info about some specific entity in a database: **info table** ``` star info table [options]
``` The `info table` sub-command prints detailed information about a table, the name of which is specified in the `
` argument, in the database referenced by the absolute or relative path given in the `` argument. The following options are available to configure the output of the command: | Option | Short form | Description | | ------------- | ---------- | -------------------------------------------------------------------------------------------- | | `--user` | `-u` | Includes user columns in the output. | | `--system` | `-s` | Includes system columns in the output. | | `--inherited` | `-i` | Includes inherited columns in the output. | | `--format` | `-f` | Lets you configure the formatting of the output by providing one or more formatting options. | Formatting options: * `c` – Include the name of the columns of the table to list. * `t` – Include the datatype of the columns of the table to list. * `n` – For each column, include whether it accepts null values in table cells. * `i` – For each column, include whether it is inherited. * `b` – Include the name of the table of the column. To list all user columns of the `MyApp.Superhero` table of an existing database located at `C:\databases\mydb`, including inherited columns and listing only the names and the datatypes of columns, we run: ``` star info table -u -i -f ct C:\databases\mydb MyApp.Superhero ``` **info index** ``` star info index [options] ``` The `info index` sub-command prints detailed information about an index, the name of which is specified in the `` argument, in the database referenced by the absolute or relative path given in the `` argument. The following options are available to configure the output of the command: | Option | Short form | Description | | ---------- | ---------- | -------------------------------------------------------------------------------------------- | | `--format` | `-f` | Lets you configure the formatting of the output by providing one or more formatting options. | Formatting options: * `c` – Include the name of the column that the index is registered on. * `b` – Include the name of the table that holds the column that the index is registered on. To list all indexes of the `MyApp.Superhero` table of an existing database located at `C:\databases\mydb`, including only the name of the column of the index, we run: ``` star info index -f c C:\databases\mydb MyApp.Superhero ``` **SQL REPL** **sql** ``` star sql [options] ``` The `star` tool includes a built-in SQL REPL (read-eval-print loop) component that can be used to execute DDL and DML statements on the database referenced by the absolute or relative path given in the `` argument. To enter the SQL REPL for an existing database located at `C:\databases\mydb`, we run: ``` star sql C:\databases\mydb ``` For more information on how to write SQL queries to a Starcounter database, and supported DDL statements, see the [SQL section](/sql.md) of the documentation. --- # 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/star-tool.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.