Proposal for new commands groups

[MarcelGeo]

Introduces new command groups which will replace "-" commands in mergin cli.

Following docs for commands:

mergin command

$ mergin --help
Usage: mergin [OPTIONS] COMMAND [ARGS]...
Command line interface for the Mergin Maps client module. For user
authentication on server there are two options:
1. authorization token environment variable (MERGIN_AUTH) is defined, or
2. username and password need to be given either as environment variables
(MERGIN_USERNAME, MERGIN_PASSWORD), or as command options (--username,
--password).
Run `mergin --username <your_user> login` to see how to set the token
variable manually.
Options:
--url TEXT Mergin Maps server URL. Default is:
https://app.merginmaps.com
--auth-token TEXT Mergin Maps authentication token string
--username TEXT
--password TEXT
--help Show this message and exit.
Commands:
file Commands related to files stored in project
login Login to the service and see how to set the...
project Commands related to projects
pull Fetch changes from Mergin Maps repository.
push Upload local changes into Mergin Maps repository.
resolve-unfinished-pull Try to resolve unfinished pull.
user User management
workspace Workspace management
Copyright (C) 2019-2025 Lutra Consulting
(python-api-client v0.9.4 / pygeodiff v2.0.4)

file sub-command

❓

• not sure if want to move to project group?
• alternative: mergin project files list

$ mergin file --help
v0.9.4 / pygeodiff v2.0.4
Usage: mergin file [OPTIONS] COMMAND [ARGS]...
Commands related to files stored in project
Options:
--help Show this message and exit.
Commands:
changeset Displays file changes.
download Download project file at specified version.
history Displays historyforfilein specified path
list List files in a project.

project sub-command

$ mergin project --help
v0.9.4 / pygeodiff v2.0.4
Usage: mergin project [OPTIONS] COMMAND [ARGS]...
Commands related to projects
Options:
--help Show this message and exit.
Commands:
clone Clone project from server.
collaborators
create Create a new project on Mergin Maps server.
download Download last version of mergin project.
list List projects on the server.
remove Remove project from server.
rename Rename project in Mergin Maps repository.
reset Reset local changes in project.
share Fetch permissions to project.
share-add Add permissions to [users] to project.
share-remove Remove [users] permissions from project.
status Show all changes in project files - upstream and local.
version Displays information about a single version of a project.

project collaborators sub-command

$ mergin project collaborators
v0.9.4 / pygeodiff v2.0.4
Usage: mergin project collaborators [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
add Add project collaborator
list List project collaborators
remove Update project collaborator
update Update project collaborator

user sub-command

❓

• not sure if here will be also login

$ mergin user --help
v0.9.4 / pygeodiff v2.0.4
Usage: mergin user [OPTIONS] COMMAND [ARGS]...
User management
Options:
--help Show this message and exit.
Commands:
register Register user

workspace sub-command

$ mergin workspace
v0.9.4 / pygeodiff v2.0.4
Usage: mergin workspace [OPTIONS] COMMAND [ARGS]...
Workspace management
Options:
--help Show this message and exit.
Commands:
members Workspace members management

workspace members sub-command

$ mergin workspace members
v0.9.4 / pygeodiff v2.0.4
Usage: mergin workspace members [OPTIONS] COMMAND [ARGS]...
Workspace members management
Options:
--help Show this message and exit.
Commands:
add Add workspace member
get Get workspace member
list List workspace members
remove Remove workspace member
update Update workspace member

❗

This is just proposal for future look of our nice cli tool.

❓

• do we want to use list for list commands? Unfortuanetely, it's not possible to create group (members) which can be also command.
• do we want to move push / pull to project? I think now it's more like git pull / push