Organizations & projects

An organization owns projects, and every sandbox runs inside one project. This page covers creating and managing both from the CLI. To switch which org/project your commands act against, see Context & config.

Every command here works two ways from one definition:

• Interactively on a terminal — missing inputs are prompted for, with the org from your active context preselected and a name suggested from the display name.
• Non-interactively — pass every input as a flag (or the positional name). This path never prompts and is the one to use for agents, scripts, and CI.

Interactive vs. non-interactive

A command runs non-interactively whenever any of the following is true, so it fails fast on a missing input instead of blocking on a prompt:

• you pass --no-input,
• you request machine output with -o json, or
• stdin is not a terminal (piped input, agents, CI).

Otherwise it runs the interactive wizard.

# Interactive: prompts for anything you leave out
tektona project create

# Scripted: every input supplied, never prompts
tektona project create reports --org acme-corp --display-name "Reports" --no-input

Organizations

tektona org ls                              # list your organizations
tektona org get [<org>]                     # details + members (defaults to context org)
tektona org create [<name>]                 # create an org (you become its owner)
tektona org update [<org>]                  # change display name, defaults

org also accepts the aliases o and orgs; get accepts show, info, and details; and create accepts new.

List

tektona org ls
tektona org ls --wide        # add ID, default location, and updated columns
tektona org ls -o json

The org in your active context is marked with *.

Get

Shows an organization's details and its members. The org defaults to your context org when no argument is given.

tektona org get
tektona org get acme-corp
tektona org get acme-corp -o json

Create

You become the owner of the org you create.

# Interactive
tektona org create

# Scripted
tektona org create --name beta-labs --display-name "Beta Labs"
tektona org new beta-labs --display-name "Beta Labs"   # positional name + alias

Update

Updating is a read-modify-write: fields you don't pass keep their current values. Requires the organization owner role. The organization name can't be changed.

tektona org update acme-corp --display-name "Acme Corporation"
tektona org update acme-corp --default-project-role reader
tektona org update acme-corp --default-location eu

Projects

tektona project ls                          # list projects across your orgs
tektona project get [<project>]             # project details + your role
tektona project create [<name>]             # create a project in an org
tektona project update [<project>]          # change display name, description

project also accepts the aliases p, proj, and projects; get accepts show, info, and details; and create accepts new. Project commands resolve the target org from --org or your active context.

List

tektona project ls                          # across every org your key can reach
tektona project ls --org acme-corp          # restrict to one org
tektona project ls --wide
tektona project ls -o json

Each row's context value (org/project) can be copied straight into tektona ctx set.

Get

tektona project get web --org acme-corp
tektona project get web --org acme-corp -o json

Create

The org comes from --org or your active context. In the wizard, if no org is set you pick one (your context org is preselected).

# Interactive (uses your context org, or prompts you to pick)
tektona project create

# Scripted
tektona project create reports \
  --org acme-corp \
  --display-name "Reports" \
  --description "Scheduled report generation"

Update

A read-modify-write — pass only what you want to change; the rest is preserved. The project name can't be changed.

tektona project update web --org acme-corp --description "Customer-facing web app"
tektona project update web --org acme-corp --display-name "Web"

Reserved names

tektona cannot be used as an organization or project name, and personal is reserved for organizations. Creating one with a reserved name is rejected with a clear error. Names are fixed once created — they can't be changed on update.

Who can do what

Roles follow the roles & permissions model:

• Any member of an org can create a project in it and becomes that project's admin.
• Updating an org requires the org owner role; updating a project requires the project admin role.
• Listing and showing are available to anyone with access to the org or project.