Skip to content
Simply SF logoSimply SF logoSimply CLI

Projects

simply gitlab project create

Section titled “simply gitlab project create”

Create a project, blank or from a template.

Flags

  • --dry-run — Print the request that would be sent and exit without sending it.
  • --name <value> — Project name. The path is derived from it when —path is not given.
  • --path <value> — Repository path, the URL slug. The name is derived from it when —name is not given.
  • --namespace <value> — Group or user namespace to create the project in, by id or full path.
  • --description <value> — Project description.
  • --visibility <value> — Who can see the project. (one of: private, internal, public)
  • --default-branch <value> — Name of the default branch.
  • --initialize-with-readme — Create a first commit holding a README, so the repository is not empty.
  • --topics <value> — Comma-separated topics to label the project with.
  • --template <value> — Template to create from: a built-in name, or with —custom-template or —template-group a custom one.
  • --custom-template — Look —template up among the instance’s custom project templates rather than the built-in ones.
  • --template-group <value> — Group whose custom project templates —template names, by id or full path.
  • --template-project <value> — Custom template project to create from, by id or full path. Cannot be combined with —template.
  • --body <value> — Raw JSON request body.
  • --body-file <value> — Path to a file holding the raw JSON request body.

Connection

  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --gitlab-url <value> — Base URL of the GitLab instance. Defaults to https://gitlab.com. (env: GITLAB_URL)
  • --gitlab-token <value> — Personal, project, or group access token. (env: GITLAB_TOKEN)

Global

  • --json — the raw API payload, for scripts and agents.

Creates the project in —namespace, or in the namespace of the token owner when none is given. Give it —name or —path; GitLab derives whichever one is missing.

—template names one of the built-in templates GitLab ships, such as express or rails. To create from a custom template instead, add —custom-template for one the instance administrator registered, —template-group for one in a group, or use —template-project to name the template project itself by id or path — which GitLab prefers, because a name can be ambiguous. Custom templates need a Premium or Ultimate instance.

A template is applied asynchronously: this command returns as soon as the project record exists, with an import status of “scheduled”, and the files arrive a few seconds later. Check “project view” until its import_status reads “finished” before writing to the repository. —dry-run prints the exact request body; a namespace or template given as a path is still looked up, so the printed ids are the ones that would be sent.

Examples

Terminal window
simply gitlab project create --name new-service --namespace platform/apps
Terminal window
simply gitlab project create --name new-service --namespace platform/apps --template express --visibility internal
Terminal window
simply gitlab project create --name new-service --namespace platform/apps --template service-skeleton --template-group platform/templates
Terminal window
simply gitlab project create --path new-service --template-project platform/templates/service-skeleton --dry-run

simply gitlab project list

Section titled “simply gitlab project list”

List projects you can see.

Flags

  • --limit <value> — Maximum number of projects to return across all pages. (default: 20)
  • --search <value> — Match against the project name and path.
  • --membership — Only projects you are a member of.
  • --owned — Only projects you own.
  • --simple — Return only the core fields, for a much smaller payload.

Connection

  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --gitlab-url <value> — Base URL of the GitLab instance. Defaults to https://gitlab.com. (env: GITLAB_URL)
  • --gitlab-token <value> — Personal, project, or group access token. (env: GITLAB_TOKEN)

Global

  • --json — the raw API payload, for scripts and agents.

Without —search this lists every project the token can reach, newest activity first, which on a large instance is not a useful answer — narrow it with —search or —membership. Use —simple for a much smaller payload when you only need ids and paths.

Examples

Terminal window
simply gitlab project list --membership
Terminal window
simply gitlab project list --search platform --limit 10
Terminal window
simply gitlab project list --search platform --simple --json

simply gitlab project view

Section titled “simply gitlab project view”

Show one project.

Flags

  • -p, --project <value> — Project id, or its full path such as group/subgroup/project. (required; env: GITLAB_PROJECT)

Connection

  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --gitlab-url <value> — Base URL of the GitLab instance. Defaults to https://gitlab.com. (env: GITLAB_URL)
  • --gitlab-token <value> — Personal, project, or group access token. (env: GITLAB_TOKEN)

Global

  • --json — the raw API payload, for scripts and agents.

Accepts either the numeric id or the full path. Use —json for the complete, unmodified API payload, which carries far more than the summary below — permissions, statistics, and every feature toggle on the project.

Examples

Terminal window
simply gitlab project view --project group/project
Terminal window
simply gitlab project view --project 1234 --json