> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> Create and manage your Aether projects

# Projects

A project is the top-level container in Aether. It groups your source code, configuration, environment variables, and workspaces into a single manageable unit.

## What's in a Project

Every project contains:

* **Source code** stored on a persistent volume inside its workspace
* **Environment variables** encrypted at rest and injected on workspace start
* **GitHub link** (optional) connecting the project to a repository
* **Workspaces** — one or more cloud VMs running your code
* **Tasks** — the history of agent work performed in the project

Each project has a unique UUID. You can reference any project by its full ID or a **short prefix** (the first 8 characters).

```
Full ID:   a1b2c3d4-e5f6-7890-abcd-ef1234567890
Short ID:  a1b2c3d4
```

## Creating a Project

<Tabs>
  <Tab title="Web">
    Click **New Project** from the dashboard. Enter a name and optional description, then click **Create**.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether project create --name "my-app" --description "A Next.js SaaS starter"
    ```

    The CLI returns the new project's ID and short prefix.
  </Tab>
</Tabs>

## Listing Projects

<Tabs>
  <Tab title="Web">
    The dashboard shows all your projects with their status and last activity.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether project list
    ```

    Output:

    ```
    ID          NAME            STATUS    CREATED
    a1b2c3d4    my-app          running   2025-03-15
    f9e8d7c6    api-service     stopped   2025-03-10
    ```
  </Tab>
</Tabs>

## Getting Project Details

```bash theme={null}
aether project get a1b2c3d4
```

Returns the full project object including name, description, workspace IDs, GitHub link, and creation date.

## Selecting a Default Project

If you work on one project frequently, set it as the default so you can omit the `--project` flag from other commands:

```bash theme={null}
aether project select
```

This opens an interactive selector. Once set, commands like `aether run`, `aether workspace connect`, and `aether env list` automatically target the selected project.

## Deleting a Project

```bash theme={null}
aether project delete a1b2c3d4 --force
```

<Warning>
  Deleting a project destroys all associated workspaces, volumes, environment variables, and task history. This action is irreversible. The `--force` flag skips the confirmation prompt.
</Warning>

## Short ID Prefix Resolution

Aether resolves short prefixes by matching against the first 8 characters of the UUID. If the prefix is ambiguous (matches multiple projects), the CLI returns an error and asks you to provide more characters.

```bash theme={null}
# These are equivalent when the prefix is unique
aether project get a1b2c3d4-e5f6-7890-abcd-ef1234567890
aether project get a1b2c3d4
```