Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

edgedb CLI command readability, verb-object regularity, usability and ergonomics

See original GitHub issue

While the following edgedb commands are clear as to what is being acted on:

edgedb create-superuser-role edgedb alter-role edgedb drop-role edgedb server reset-password

most CLI commands are more cryptic.

What would be the impact on the cognitive load for learners and developers, if we made both the verb and the object clear in the canonical version of CLI commands?

There are many approaches to regularising naming conventions. I’m not precious about which approach is chosen, just keen on improving usability and ergonomics.

I’m interested in contributing. If the edgedb team is supportive of this direction, then I am interested in assisting creation of the pull requests to chip away at this refactoring of code and documentation over coming releases. Let me know if this is of interest.

Command	Possible Canonical Version Showing Verb-Object	Other possibilities.
`edgedb configure`	`edgedb configure-instance`	Or possibly `edgedb instance configure`
`edgedb create-migration`	`edgedb create-migration-database`	Or possibly `edgedb database create-migration`
`edgedb dump`	`edgedb dump-database`
`edgedb migrate`	`edgedb migrate-database`
`edgedb migration-log`	`edgedb migration-log-database`
`edgedb project init`	`edgedb project init-instance`
`edgedb project unlink`	`edgedb project unlink-instance`
`edgedb restore`	`edgedb restore-database`
`edgedb self-upgrade`	`edgedb server self-upgrade`	Moving this command into the `server` namespace.
`edgedb server destroy`	`edgedb server destroy-instance`
`edgedb server info`	`edgedb server info-version`
`edgedb server init`	`edgedb server init-instance`	Or possibly `edgedb instance init`
`edgedb server install`	`edgedb server install-version`
`edgedb server list-versions`	`edgedb server list-version`
`edgedb server logs`	`edgedb server logs-instance`
`edgedb server revert`	`edgedb server revert-instance`
`edgedb server start`	`edgedb server start-instance`
`edgedb server status`	`edgedb server status-instance`
`edgedb server stop`	`edgedb server stop-instance`
`edgedb server uninstall`	`edgedb server uninstall-version`
`edgedb server upgrade`	`edgedb server upgrade-instance`
`edgedb show-status`	`edgedb show-migration-status-database`

Issue Analytics

State:
Created 2 years ago
Comments:7 (4 by maintainers)

Top GitHub Comments

1reaction

1st1commented, Aug 12, 2021

@DavidPratten We’ve release EdgeDB b3 with your recommendations implemented, David. Thanks so much for bringing this topic up! https://www.edgedb.com/blog/edgedb-beta-3-ross

1reaction

1st1commented, Jul 5, 2021

database dump

We considered this, but the dump command can also dump multiple different databases at once. So nesting it into the database subgroup would be confusing.

If the names of configurable flags/settings clearly indicate the object then this would be clear to developers. Otherwise consider database config , server config and instance config.

BTW, thanks to your GH threads we’re keeping the edgedb configure name (the current edgedb config rename was done by mistake; I’ll fix the RFC today). I’m not sure that splitting configuration into separate three commands would make it simpler, conceptually.

instance init

I’m on the fence about this suggestion. There pros – it’s logical, and cons - more to type, more nesting. We’ll discuss this proposal on one of our engineering calls this Wednesday or Friday.

Top Results From Across the Web

The EdgeDB CLI

The edgedb command-line interface (CLI) provides an idiomatic way to install EdgeDB, spin up local instances, open a REPL, execute queries, ...

The CLI — Get Started | EdgeDB Docs

The edgedb command line tool is an integral part of the developer workflow of building with EdgeDB. Below are instructions for installing it....

Network usage — CLI | EdgeDB Docs

Generally command-line tools connect only to the database host. But there are two exceptions: When the command-line tool starts, it checks if its...

edgedb database create — CLI

The database create command runs in the EdgeDB instance it is connected to. For specifying the connection target see connection options.

Interactive Shell — CLI | EdgeDB Docs

Specifies the named instance to connect to. The actual connection parameters are stored in <edgedb_config_dir>/credentials and are usually created by edgedb ...