Skip to main content

Using the Shell

The shell is an interactive tool in which you can

  • Experiment with Angle queries
  • Explore the data in a Glean database
  • Experiment with schema changes and derived predicates
  • Create experimental databases and query them

Invoking the shell​

glean shell --service HOST:PORT

to connect to a server, or

glean shell --db-root DIR

to use local databases from directory DIR.

See shell options for more command-line options.

Quick start​

  • List the available databases with :list
  • Select a database with :db NAME
  • See the contents of the database with :stat
  • Type queries in Angle to see the results.

Shell options​

The shell accepts all the common options. Additionally:

  • QUERY or :COMMAND
    Perform the given QUERY or :COMMAND and then exit. If multiple commands or queries are given on the command line, they will be performed in left-to-right order.
  • --db NAME or --db NAME/HASH
    Load the database NAME or NAME/HASH.
  • --limit N
    Set the default limit for queries; equivalent to the :limit command.
  • --width N
    Set the terminal width for pretty-printing results.
  • --pager
    Enable automatic paging of results longer than a page.
  • -v|--verbose N
    Enabled verbosity at level N

Commands

Note that you can abbreviate commands as long as the abbreviation is unique. For example, :edit can be abbreviated as :e.

  • :database NAME or :database NAME/HASH
    Use database NAME or NAME/HASH.
  • :list NAME
    List available databases which match NAME.
  • :list-all NAME
    List available databases, and restorable backups, which match NAME.
  • :index LANGUAGE DIR
    Index some source code for LANGUAGE in directory DIR, creating a new database. This command is only available with the --db-root option. Currently the only supported languages are flow, hack, and haskell.
  • :debug off|[-]ir|[-]bytecode|all
    Enable query debugging; :debug ir shows the intermediate representation of the query after optimisation; :debug bytecode shows the compiled bytecode.
  • :describe NAME
    Like :list, but show more details
  • :describe-all NAME
    Like :list-all, but show more details
  • :schema [PREDICATE|TYPE]
    Show schema for the given PREDICATE or TYPE, or the whole schema if no predicate or type is given.
  • :use-schema [current|stored|<schema-id>]
    With no arguments, shows the available schemas and the current setting. With an argument, selects the schema to use for queries and inspecting with the :schema command:
    • current: selects the current schema.
    • stored: selects the schema stored in the current DB.
    • <schema-id>: selects the specified schema.
  • :edit
    Edit a query in an external editor. Set the EDITOR environment variable to choose an editor.
  • :limit N
    Set limit on the number of query results. If there are more results than the limit, then you can type :more to fetch the next N results.
  • :load [<file> | <db>/<hash> <file> ...]
    Create a new DB, loading facts from the given file(s).
    • <file> is a file of facts in JSON format
    • <db>/<hash> optionally the name of the DB to create
  • :create [<db>/<hash>]
    Create a new empty DB.
    • <db>/<hash> optionally the name of the DB to create Set the query time budget. If the time limit expires, the results so far are returned, and you can type :more to see more results.
  • :expand off|on
    Recursively expand nested facts in the response. on by default.
  • :pager off|on
    Enable/disable result paging.
  • :count QUERY
    Show only a count of query results, not the results themselves
  • :more
    Fetch more results from the previous query
  • :profile [off|summary|full]
    Show query profiling information; see Query Debugging.
  • :reload
    Reload the schema (when using --schema). This command is useful when making changes to the schema, including derived predicates. Edit the schema source files, :reload and then test your changes.
  • :statistics [PREDICATE]
    Show statistics for the current database.
  • :quit
    Leave the shell.