Skip to main content
Manage your Aether projects. A project groups source code, environment variables, an optional GitHub link, task defaults, and the history of agent runs. See the Projects guide for concepts.

Usage

projects is an alias for project.

Subcommands

Most <id> arguments accept a short prefix. readiness acts on the project --project names, else your default project. The MCP servers, plugins and default skills a project enables are listed, enabled and disabled with aether mcp, aether plugin and aether skill, naming the project with --project.

aether project list

Projects with no linked repository show — in the REPO column. With --archived, the last column is ARCHIVED, when each project was archived, and each row names its project by its full ID, since short prefixes resolve against live projects only. With no archived projects it prints No archived projects.

aether project get

Show full details for one project.

aether project create

Linking the repository is for an owner or admin of the organization you act in, because every owner, admin, member and viewer of the organization will be able to read its code; for any other role the API refuses the link after the project is created, and the command names that project. The repository is resolved before anything is created, through the GitHub App installation that reaches it with your push access, and one no installation reaches creates nothing: connect GitHub or grant the App access first. A repository the App stops reaching between that check and the link leaves the project created and unlinked, and the command prints how to link it.

aether project update

Update the settings of the web app’s General, Task defaults and PR reviews tabs. Only the flags you pass are sent, and every setting you leave out keeps its value: --post-pr-screenshots true sends that one task default. --agent-type, --model and --reasoning-effort are one agent selection: passing any of them reads the project and sends all three together, so a model is resolved for a new agent type. Only an owner or admin of the project’s organization updates a project; a member is refused with control_forbidden.
General: Task defaults: PR reviews, the settings of the project’s repository. A project with no repository refuses them with project_has_no_repository; link one first:
Running update with no flags returns an error — provide at least one.

aether project archive

Archive a project by setting its archived field (PATCH /projects/{id}). Live activity stops and the project is hidden from normal views, while task, run, and billing history is retained.
The project is archived at once, and its workspaces, warm slots and automations are released in the background. Without --json, a project that was already archived prints Project "my-app" was already archived. With --json, the CLI prints only the project the API answers with: its archive is {"state": "archived", "at": …}.
Archiving destroys the project’s active workspaces and volumes, deletes its automations, and removes its environment variables, secret files, and integration routes. Task, run, and billing history is kept. The CLI has no unarchive command. PATCH /projects/{id} with archived: false restores the project but none of what archiving removed, and is refused while another live project holds its repository or its PR review triggers.

aether project select

Set the default project for all commands. With no argument, opens an interactive picker.
Once set, commands like aether run and aether env target this project automatically.

aether project readiness

Check whether your tasks in the project can start. It lists:
  • the required servers that refuse your tasks, because the connection their credential policy names does not exist or needs reauthorization
  • the optional servers your tasks start without
  • the declarations in the repository’s .mcp.json and .codex/config.toml that your tasks start without
Any owner, admin or member of the project’s organization can check it.
A server the repository declares is marked (no matching catalog server enabled) when no catalog server the project enables has its URL: the catalog may lack one, which an admin adds with aether mcp add, or hold one the project does not enable, which an admin enables with aether mcp enable. You then connect it with aether mcp connect. When nothing is missing, it prints Your tasks in the project can start with every MCP server it gives them.