The quickest way to add a new space in Gemini CLI

To create a new space in Gemini CLI, type gemini space create [space-name] at your command prompt and press Enter. Replace [space-name] with whatever you want to call your space — use lowercase letters, numbers, and hyphens only. The CLI will confirm the space was created and show you its ID.

A space in Gemini CLI is a contained environment where you can organize conversations, files, or projects separately from your other work. Once created, you can switch into that space and start using it immediately without any additional setup.

Key Takeaways

  • Use gemini space create [name] to make a new space, where the name uses only lowercase letters, numbers, and hyphens.
  • Each space gets its own ID automatically, which you can see by running gemini space list to view all your spaces.
  • Switch into a space with gemini space enter [space-name] or gemini space enter [space-id] to start working in it.
  • Spaces keep their contents separate from each other, so files and settings in one space do not affect another.
  • You can delete a space with gemini space delete [space-name], but this removes everything inside it permanently.

Viewing your existing spaces before creating a new one

Before you create a space, it helps to see what spaces you already have. Type gemini space list to see all your spaces in a table with their names and IDs. This prevents you from accidentally creating a space with a name you already use.

The list shows the space name in the first column and the space ID in the second. You can use either one to enter a space or perform actions on it — the CLI accepts both.

Naming your space so you can find it later

Space names should describe what you plan to use them for. Good names are short and specific: project-alpha, client-notes, experiments, or archive-2024. Avoid spaces, uppercase letters, and special characters — the CLI will reject them.

If you create a space with a name you do not like, you cannot rename it. You would need to create a new space with the correct name and move your files manually, or delete the old space and start over. Choose the name carefully the first time.

Entering your new space and starting to use it

After you create a space, you are still in your previous location. To start working inside the new space, type gemini space enter [space-name] (or use the space ID instead of the name). Your prompt will change to show you are now inside that space.

Once you are inside a space, any files you create, any conversations you start, or any settings you change apply only to that space. When you exit the space and enter a different one, those changes stay behind — they do not follow you.

Moving files and content between spaces

If you create a space and then realize you want to move something into it from another space, you can copy or move files using standard CLI commands. First, make sure you know the file path in the source space, then enter your new space and use cp or mv to bring the file in.

The exact syntax depends on whether the file is in your current space or another one. If you are moving a file from outside your current space, you may need to use the full path or reference the other space by name. Check the file location with ls before you move anything, so you do not accidentally move the wrong file.

Deleting a space you no longer need

To remove a space entirely, type gemini space delete [space-name] and confirm when prompted. This action cannot be undone — the space and everything inside it will be gone permanently. The CLI will ask you to confirm before it deletes, so read the prompt carefully.

If you are not sure whether you need a space, consider renaming it to something like old-space-archive instead of deleting it. That way you keep the contents but signal to yourself that you are not actively using it. You can always delete it later if you confirm you do not need it.

Troubleshooting common space creation problems

If the CLI rejects your space name, check that it contains only lowercase letters, numbers, and hyphens. Names like My Space, Project-2024!, or TEST will fail. Rename it to my-space, project-2024, or test instead.

If you get a message that the space already exists, run gemini space list to see your current spaces. You may have created it before and forgotten, or someone else on your system may have created it. Enter the existing space instead of creating a new one, or choose a different name.

If you cannot enter a space after creating it, make sure you are using the correct name or ID. Spaces are case-sensitive on most systems, so my-space and My-Space are different. Check the exact spelling with gemini space list and try again.

Frequently Asked Questions

Can I rename a space after I create it?

No, Gemini CLI does not have a rename command for spaces. If you need a different name, create a new space with the correct name, move your files into it, and then delete the old space.

What happens to my files if I delete a space?

Everything inside the space is deleted permanently. The CLI will ask you to confirm before it deletes, so read the confirmation message carefully. If you are unsure, do not confirm — you can always delete it later.

Can multiple people use the same space?

That depends on your Gemini CLI setup and permissions. By default, spaces are personal to your user account. Check your system administrator or documentation if you need to share a space with others.

How many spaces can I create?

There is no hard limit on the number of spaces you can create. However, each space uses some disk space for its contents, so creating hundreds of empty spaces is wasteful. Create spaces for things you actually plan to use.

Can I see what is inside a space without entering it?

Yes, use gemini space info [space-name] to see details about a space, including its size and when it was created. To see the actual files inside, you need to enter the space with gemini space enter and then use ls.