Zeabur CLI

https://github.com/zeabur/cli
Admin
Zeabur CLI is Zeabur's official command-line tool designed for managing Zeabur resources, offering...
Tokens:115,637
Snippets:772
Trust Score:9.4
License:MPL-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Usage example: setting project and clearing pins

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/zcontext.md

Shows how to get the current context, set a project, clear service and environment pins, check if the workspace is a team, and create an ephemeral context for a team workspace override.

```go
ctx := f.Config.GetContext()
ctx.SetProject(zcontext.NewBasicInfo(project.ID, project.Name))
// setting a project clears env/service pins (done by the command layer):
ctx.ClearService()
ctx.ClearEnvironment()

ws := ctx.GetWorkspace()
if ws.IsTeam() { /* owner-scoped lookups use ws.ID */ }

// one-shot override contexts created by Factory.EffectiveContext():
eph := zcontext.NewEphemeralContext(&zcontext.Workspace{ID: team.ID, Name: team.Name, Kind: zcontext.WorkspaceKindTeam})
```

--------------------------------

### Usage example: service, variables, and deployment

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-service.md

Shows how to resolve a service by name, list and update variables, and get the latest deployment. The variable update merges writable variables with a new key and writes back. The deployment retrieval returns an exists flag.

```go
// service by name within the active workspace (team-safe resolution):
service, err := util.GetServiceByName(f.ApiClient, f.CurrentOwnerID(),
	f.Config.GetUsername(), f.CurrentProjectName(), f.CurrentProjectID(), "web")

// variables: read → merge → write
writable, readonly, err := f.ApiClient.ListVariables(ctx, svc.ID, env.ID)
merged := writable.ToMap()
merged["KEY"] = "value"
ok, err := f.ApiClient.UpdateVariables(ctx, svc.ID, env.ID, merged)
if err != nil || !ok { /* failure */ }

// latest deployment
dep, exists, err := f.ApiClient.GetLatestDeployment(ctx, svc.ID, env.ID)
if err != nil { return err }
if !exists { /* no deployment found */ }
```

--------------------------------

### Typical usage of zeabur email commands

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-email.md

Shows a typical workflow: resource setup via GraphQL (using session token) and sending emails via REST (using zs_ key). Includes commands for status, domains, keys, send, scheduled list, and batch get.

```shell
# resource setup (GraphQL, uses the session token)
npx zeabur email status
npx zeabur email domains add --domain mail.example.com --region us
npx zeabur email keys create --name prod --permission send --domains mail.example.com

# sending (REST, uses the zs_ key)
npx zeabur email send --api-key zs_xxx --from "no-reply@example.com" \
  --to user@example.com --subject "Hello" --html "<p>Hi</p>"
npx zeabur email send --api-key zs_xxx --from a@example.com --to b@example.com \
  --subject "Later" --html "<p>bye</p>" --scheduled-at 2026-04-01T10:00:00Z
npx zeabur email send --api-key zs_xxx --batch-file emails.json
npx zeabur email scheduled list --api-key zs_xxx
npx zeabur email batch get  --api-key zs_xxx --id JOB_ID
```

--------------------------------

### Usage example for auth login flow

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/auth.md

Shows how to create a callback server, set it as the auth client, and generate a token during login. The token is then stored in the config.

```go
cbs, err := auth.NewCallbackServer()
if err != nil { /* internal error */ }
f.AuthClient = auth.NewImplicitFlowClient(cbs)

// inside the root PersistentPreRunE / `auth login`:
token, err := f.AuthClient.GenerateToken(context.Background())
if err != nil {
	return fmt.Errorf("failed to login: %w", err)
}
f.Config.SetTokenString(token)
```

--------------------------------

### Usage example for reading and writing config

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/config.md

Illustrates how to access the configuration through factory.Config. It shows reading the stored token, persisting a new token after login, and updating the inner context with project information.

```go
// wiring (cmd/main.go): factory.Config = config.New(config.DefaultConfigFilePath())

// read stored credential
token := factory.Config.GetTokenString()

// persist a fresh token after browser login
factory.Config.SetTokenString(token)

// inner context is live, not a snapshot
factory.Config.GetContext().SetProject(zcontext.NewBasicInfo(project.ID, project.Name))
```

--------------------------------

### Prompter usage example

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/printer-prompt-log.md

Example usage of Prompter methods: Select, Confirm, and ConfirmDeletion with error handling.

```go
idx, err := f.Prompter.Select("Select project", projectsName[0], projectsName)
ok, err := f.Prompter.Confirm("Are you sure to delete project", false)
if err := f.Prompter.ConfirmDeletion(project.Name); err != nil { return err }
```

--------------------------------

### Watching runtime logs example

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-service.md

Shows how to use WatchRuntimeLogs to stream logs and print them as a table or JSON. The channel is closed when the subscription loop ends.

```go
logChan, err := f.ApiClient.WatchRuntimeLogs(ctx, proj.ID, svc.ID, env.ID, deploymentID)
if err != nil { return fmt.Errorf("failed to watch logs: %w", err) }
for log := range logChan {
	f.Printer.Table(log.Header(), log.Rows())   // or f.Printer.JSON(log)
}
```

--------------------------------

### GetUserInfo usage example

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-project.md

Example of calling GetUserInfo to fetch user information, handling errors, and setting user config fields. Used by auth login/status and profile info commands.

```go
user, err := f.ApiClient.GetUserInfo(context.Background())
if err != nil { return fmt.Errorf("failed to get user info: %w", err) }
f.Config.SetUser(user.Name)
f.Config.SetUsername(user.Username)
```

--------------------------------

### Get help for any command

Source: https://github.com/zeabur/cli/blob/main/README.md

Shows help information for any Zeabur CLI command.

```shell
npx zeabur <command> --help
```

--------------------------------

### Printer usage example

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/printer-prompt-log.md

Example usage of the Printer interface: printing a table with header and rows, and printing a JSON value with error handling.

```go
f.Printer.Table(projects.Header(), projects.Rows())
if err := f.Printer.JSON(user); err != nil { return err }
```

--------------------------------

### Format code with gofumpt

Source: https://github.com/zeabur/cli/blob/main/CONTRIBUTING.md

Format the codebase using gofumpt. Requires gofumpt to be installed.

```bash
gofumpt -w .
```

--------------------------------

### Run from Source Code

Source: https://github.com/zeabur/cli/blob/main/docs/development_guide.md

Run the CLI directly from source using the Go run command. Example: `go run cmd/main.go auth login --debug`.

```shell
go run cmd/main.go auth login --debug
```

--------------------------------

### Usage examples for FormatHTTPError and UploadTimeout

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/util-pkg.md

Two usage examples: one fails an upload step with the backend's message and code using FormatHTTPError, and the other scales a deadline to payload size using UploadTimeout.

```go
// fail an upload step with the backend's own message + code:
if resp.StatusCode != http.StatusCreated {
	return "", pkgutil.FormatHTTPError("failed to create upload session", resp)
}

// scale a deadline to payload size:
deadline := util.UploadTimeout(int64(len(zipBytes)))
```

--------------------------------

### Send Z-Send email example

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-zsend-aihub-file.md

Shows how to send an email using the ZSendAPI client. Requires a Z-Send API key (e.g., "zs_..."). The request includes From, To, Subject, and HTML content.

```go
req := model.ZSendSendEmailRequest{
	From:    "no-reply@example.com",
	To:      []string{"hi@example.com"},
	Subject: "Hello",
	HTML:    "<p>Hi</p>",
}
reply, err := client.SendZSendEmail(ctx, apiKey /* "zs_..." */, req)
if err != nil { return fmt.Errorf("send email failed: %w", err) }
```

--------------------------------

### Example commit message in Conventional Commits format

Source: https://github.com/zeabur/cli/blob/main/CONTRIBUTING.md

Example commit message following the Conventional Commits format, with a type, scope, and subject.

```plain
feat(cmd/service): Optimization for user experience

This commit add multiple selectors for user to select services interactively.  
```

--------------------------------

### Lint code with make lint

Source: https://github.com/zeabur/cli/blob/main/CONTRIBUTING.md

Lint the codebase using the Makefile target. Requires golangci-lint to be installed.

```bash
make lint
```

--------------------------------

### Manage resources in interactive mode

Source: https://github.com/zeabur/cli/blob/main/README.md

Interactive mode commands for listing projects, setting contexts, restarting services, and getting deployment info/logs. Use arrow keys to select projects when setting context.

```shell
# list all projects
npx zeabur project ls

# set project context, the following commands will use this project context
# you can use arrow keys to select the project
npx zeabur context set project

# list all services in the project
npx zeabur service ls

# set service context(optional)
npx zeabur context set service

# set environment context(optional)
npx zeabur context set env

# restart the service
npx zeabur service restart

# get the latest deployment info
npx zeabur deployment get

# get the latest deployment log(runtime)
npx zeabur deployment log -t=runtime

# get the latest deployment log(build)
npx zeabur deployment log -t=build
```

--------------------------------

### Config interface

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/config.md

The Config interface provides methods to get and set the token, user, username, and inner context, as well as write the configuration to disk.

```APIDOC
## Config interface

### Description
Provides methods to access and modify persistent configuration values such as token, user, username, and inner context, and to flush changes to disk.

### Methods

#### GetTokenString
- **Signature**: `GetTokenString() string`
- **Description**: Returns the stored token string (`zat_…` access token or legacy `sk-…` API key); `""` when not logged in.

#### SetTokenString
- **Signature**: `SetTokenString(token string)`
- **Description**: Persists a token string. Used by `auth login` and the root auto-login.

#### GetUser
- **Signature**: `GetUser() string`
- **Description**: Returns the user nickname.

#### SetUser
- **Signature**: `SetUser(user string)`
- **Description**: Sets the user nickname.

#### GetUsername
- **Signature**: `GetUsername() string`
- **Description**: Returns the username (GitHub-like id).

#### SetUsername
- **Signature**: `SetUsername(username string)`
- **Description**: Sets the username.

#### GetContext
- **Signature**: `GetContext() zcontext.Context`
- **Description**: Returns the inner workspace/project/environment/service context.

#### Write
- **Signature**: `Write() error`
- **Description**: Flushes the configuration to disk via `viper.WriteConfig()`.

### Usage Example
```go
// read stored credential
token := factory.Config.GetTokenString()

// persist a fresh token after browser login
factory.Config.SetTokenString(token)

// inner context is live, not a snapshot
factory.Config.GetContext().SetProject(zcontext.NewBasicInfo(project.ID, project.Name))
```
```

--------------------------------

### Usage example of DefaultIDNameByContext

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/internal-util.md

Shows how to use DefaultIDNameByContext in a PreRunE, passing a closure that returns the project from the effective context. The closure ensures resolution happens after --workspace is parsed.

```go
PreRunE: util.DefaultIDNameByContext(
	func() zcontext.BasicInfo { return f.EffectiveContext().GetProject() },
	&opts.id, &opts.name,
),
```

--------------------------------

### Constructor and initialization functions

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/config.md

Shows the constructor function New and the helper functions for initializing the configuration. New calls initViper and returns a config instance with a Viper-backed context.

```go
func New(path string) Config
```

```go
func DefaultConfigFilePath() (string, error)
func initViper(configPath string)
func createConfigFile(configPath string)
```

--------------------------------

### Select project, service, and environment

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/selector.md

Shows how to use the Selector to select a project, service, and environment. The first call selects a project, creating one if the user picks "Create a new project". The second call prefers creating a new project, used by `template deploy`. The third call selects a service with filtering and auto-selection, and the fourth selects an environment.

```go
// select a project, creating one if the user picks "Create a new project"
projectInfo, project, err := f.Selector.SelectProject()
if err != nil { return err }

// prefer creating a new project (used by `template deploy`)
projectInfo, project, err := f.Selector.SelectProject(selector.WithCreatePreferred())

// services, filtered and auto-selecting when alone
info, svc, err := f.Selector.SelectService(selector.SelectServiceOptions{
	ProjectID:  project.ID,
	Auto:       true,
	CreateNew:  true,
	FilterFunc: func(s *model.Service) bool { return s.Template == "GIT" },
})
if svc == nil {
	// no service matched / user chose create — caller handles it
}

envInfo, env, err := f.Selector.SelectEnvironment(project.ID)
```

--------------------------------

### zeabur email emails get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-email.md

Gets a specific email record by ID. Uses GraphQL and the session token.

```APIDOC
## [CLI] zeabur email emails get

### Description
Gets a specific email record by ID. Uses GraphQL and the session token.

### Command
`zeabur email emails get`

### Parameters
#### Arguments
- `id` (string) - Required - The email record ID.

### Response
Returns the email record details.
```

--------------------------------

### Build and Run Binary

Source: https://github.com/zeabur/cli/blob/main/docs/development_guide.md

Build the CLI binary with `make build` and then run it with `./zeabur auth login --debug`.

```shell
make build
```

```shell
./zeabur auth login --debug
```

--------------------------------

### zeabur email scheduled get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-email.md

Gets a specific scheduled email by ID. Uses REST and requires an API key.

```APIDOC
## [CLI] zeabur email scheduled get

### Description
Gets a specific scheduled email by ID. Uses REST and requires an API key.

### Command
`zeabur email scheduled get`

### Parameters
#### Flags
- `--api-key` (string) - Required - The API key for authentication.
- `--id` (string) - Required - The scheduled email ID.

### Response
Returns the scheduled email details.
```

--------------------------------

### zeabur email batch get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-email.md

Gets a specific batch email job by ID. Uses REST and requires an API key.

```APIDOC
## [CLI] zeabur email batch get

### Description
Gets a specific batch email job by ID. Uses REST and requires an API key.

### Command
`zeabur email batch get`

### Parameters
#### Flags
- `--api-key` (string) - Required - The API key for authentication.
- `--id` (string) - Required - The batch job ID.

### Response
Returns the batch email job details.
```

--------------------------------

### Project API client usage (list, create, clone, dedicated servers)

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-project.md

Shows how to use the Zeabur CLI API client for project operations. Requires an API client (e.g., api.New(token)) and a team ID from factory.CurrentOwnerID(). Lists projects, creates one under a team, clones it and polls status until completion or failure, and queries dedicated server providers, regions, and plans.

```go
client := f.ApiClient // api.New(token) — see api-client.md
ctx := context.Background()

// owner-scoped listing (team workspace): teamId from factory.CurrentOwnerID()
projects, err := client.ListAllProjects(ctx, teamId)
if err != nil { return fmt.Errorf("list projects failed: %w", err) }

// create under a team; empty ownerID = personal
proj, err := client.CreateProject(ctx, teamId, "sfo0", nil)

// clone + poll
res, err := client.CloneProject(ctx, proj.ID, envID, "tpe0", false)
for {
	status, err := client.CloneProjectStatus(ctx, res.NewProjectID)
	// stop on CloneProjectCompleted / CloneProjectFailed / status.Error
}

// dedicated server catalog
providers, err := client.ListDedicatedServerProviders(ctx)
regions, err := client.ListDedicatedServerRegions(ctx, providers[0].Code)
plans, err := client.ListDedicatedServerPlans(ctx, providers[0].Code, regions[0].ID)
```

--------------------------------

### Build, Run, and Test Commands

Source: https://github.com/zeabur/cli/blob/main/CLAUDE.md

Standard Go commands for building, running, and testing the CLI. Use `go build ./...` to compile, `go run ./cmd/main.go <command>` to run a command, and `go test ./...` to run tests.

```bash
go build ./...
```

```bash
go run ./cmd/main.go <command>
```

```bash
go test ./...
```

--------------------------------

### zeabur server get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-server-aihub-template.md

Gets details for a specific dedicated server. The server ID can be provided as a positional argument or via the `--id` flag.

```APIDOC
## zeabur server get

### Description
Gets details for a specific dedicated server. The server ID can be provided as a positional argument or via the `--id` flag.

### Method
CLI command

### Command
`zeabur server get [server-id]`

### Parameters
#### Flags
- `--id <string>` (string) - Optional - Server ID. Can also be provided as a positional argument.

#### Positional Arguments
- `[server-id]` (string) - Optional - Server ID.

```

--------------------------------

### NewBasicInfo constructor

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/zcontext.md

Creates a BasicInfo with the given id and name. Used to set project, environment, or service pins.

```go
func NewBasicInfo(id, name string) BasicInfo
```

--------------------------------

### zeabur template get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-server-aihub-template.md

Gets a template by its code. Requires `--code` in non-interactive mode. With `--raw`, outputs the raw YAML spec from the marketplace.

```APIDOC
## zeabur template get

### Description
Retrieves a template by its unique code. In non-interactive mode, `--code` is required. With `--raw`, streams the raw YAML specification from the marketplace URL.

### Method
CLI

### Command
`zeabur template get`

### Parameters
#### Flags
- `-c, --code <string>` (string, default "") - Required in non-interactive mode. The template code.
- `--raw` (bool, default false) - If true, outputs the raw YAML spec from `https://zeabur.com/templates/{code}.yaml`.

### Behaviour
- If `--raw` is set, fetches the YAML from the marketplace. Non-200 HTTP status results in error `template not found (HTTP %d)`.
- Otherwise, prints the template's Code, Name, and Description. If not found, prints "Template not found".

### Response
#### Success Response
- When `--raw`: raw YAML content.
- Otherwise: human-readable output with Code, Name, Description.

#### Error Response
- Missing `--code` in non-interactive mode: `template code is required`.
- Non-200 HTTP when fetching raw YAML: `template not found (HTTP %d)`.
```

--------------------------------

### Main function and initFactory in cmd/main.go

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/main-and-root.md

The main function initializes the factory, creates the root command, defaults to the deploy command if no arguments are given, and executes the root command, logging errors and exiting with code 1 on failure. The initFactory function sets up the factory with config, printer, auth client, and prompter dependencies.

```go
var (
	version = "dev"
	commit  = "none"
	date    = time.Now().Format(time.RFC3339)
)

func main() {
	factory := initFactory()

	rootCmd, err := root.NewCmdRoot(factory, version, commit, date)
	if err != nil {
		panic(err)
	}

	if len(os.Args) <= 1 {
		os.Args = append([]string{os.Args[0], "deploy"}, os.Args[1:]...)
	}

	// log errors and exit non-zero so callers can tell a failure from success
	if err := rootCmd.Execute(); err != nil {
		// when some errors occur(such as args dis-match), the log may not be initialized
		if factory.Log == nil {
			factory.Log = log.NewInfoLevel()
		}
		factory.Log.Error(err)
		os.Exit(1)
	}
}

// init factory, including config, auth, etc.
func initFactory() *cmdutil.Factory {
	factory := cmdutil.NewFactory()

	configPath, err := config.DefaultConfigFilePath()
	if err != nil {
		panic(err)
	}
	factory.Config = config.New(configPath)

	factory.Printer = printer.New()

	cbs, err := auth.NewCallbackServer()
	if err != nil {
		panic(fmt.Sprintf("failed to create callback server (internal error): %v", err))
	}

	factory.AuthClient = auth.NewImplicitFlowClient(cbs)

	factory.Prompter = prompt.New()

	return factory
}
```

--------------------------------

### Zeabur CLI client usage in Go

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-zsend-aihub-file.md

Shows how to use the Zeabur CLI Go client for templates, domains, AI Hub, and file uploads. Includes calls to GetTemplate, DeployTemplate, CheckDomainRegistrationAvailability, PurchaseDomain, ListDNSRecords, GetAIHubTenant, GetAIHubMonthlyUsage, and PullUploadFiles.

```go
// template
tpl, err := client.GetTemplate(ctx, "nextjs")
res, err := client.DeployTemplate(ctx, rawSpecYaml, model.Map{}, model.RepoConfigs{}, projID)

// registered domains
result, err := client.CheckDomainRegistrationAvailability(ctx, "example.com")
invoice, err := client.PurchaseDomain(ctx, "example.com", profileID)
records, err := client.ListDNSRecords(ctx, domainID)

// AI Hub
tenant, err := client.GetAIHubTenant(ctx)
usage, err := client.GetAIHubMonthlyUsage(ctx, &"2026-01")

// uploaded files
count, skipped, err := client.PullUploadFiles(ctx, uploadID, "./out")
```

--------------------------------

### New(path string) Config

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/config.md

Constructor that creates a new Config instance backed by Viper, initializing the Viper instance with the given path.

```APIDOC
## New(path string) Config

### Description
Creates a new Config instance. Calls `initViper(path)` and returns a `&config{path: path, ctx: zcontext.NewViperContext(viper.GetViper())}`.

### Parameters
- **path** (string) - Required - The file path to the configuration file.

### Returns
- **Config** - The new Config instance.

### Example
```go
config := config.New(config.DefaultConfigFilePath())
```
```

--------------------------------

### DeploymentAPI interface definition

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-service.md

Defines the DeploymentAPI interface with methods for listing deployments, listing all deployments, getting a deployment by ID, and getting the latest deployment. ListAllDeployments calls ListDeployments with perPage=5 and flattens one page. GetDeployment returns nil when absent. GetLatestDeployment returns applied=false when there are no edges.

```go
	DeploymentAPI interface {
		ListDeployments(ctx context.Context, serviceID string, environmentID string, perPage int) (*model.DeploymentConnection, error)
		ListAllDeployments(ctx context.Context, serviceID string, environmentID string) (model.Deployments, error)
		GetDeployment(ctx context.Context, id string) (*model.Deployment, error)
		GetLatestDeployment(ctx context.Context, serviceID string, environmentID string) (*model.Deployment, bool, error)
	}
```

--------------------------------

### zeabur email webhooks get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-email.md

Retrieves a specific Z-Send webhook by ID.

```APIDOC
## `zeabur email webhooks get`

### Description
Retrieves a specific Z-Send webhook by ID.

### Method
CLI Command

### Command
`zeabur email webhooks get`

### Parameters
#### Arguments
- `id` (string) - Required - The webhook ID.

### Response
Returns the webhook details.
```

--------------------------------

### Project connection, edge, usage, and list types

Source: https://github.com/zeabur/cli/blob/main/_autodocs/types.md

Defines ProjectConnection, ProjectEdge, ProjectUsage, and Projects types. ProjectUsage includes CPU in vCPU-minutes and Memory in MB-minutes.

```go
type ProjectConnection struct {
	PageInfo *PageInfo      `json:"pageInfo"`
	Edges    []*ProjectEdge `json:"edges"`
}
type ProjectEdge struct {
	Node   *Project `json:"node"`
	Cursor string   `json:"cursor"`
}
type ProjectUsage struct {
	Project *Project `json:"project"`
	From time.Time `json:"from"`
	To time.Time `json:"to"`
	CPU float64 `json:"cpu"`      // vCPU-minutes
	Memory int `json:"memory"`    // MB-minutes
}
type Projects []*Project
```

--------------------------------

### Prompter constructor and constant

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/printer-prompt-log.md

New returns a Prompter backed by survey. defaultPageSize is used for select page size.

```go
func New() Prompter
const defaultPageSize = 10
```

--------------------------------

### zeabur email domains get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-email.md

Retrieves details for a specific email domain by its ID.

```APIDOC
## zeabur email domains get

### Description
Retrieves details for a specific email domain by its ID.

### Command
`zeabur email domains get`

### Parameters
#### Flags
- **--id** (string) - Required - Domain ID
```

--------------------------------

### CreateServiceInput, MarketplaceItem, PrebuiltItem, GitRepo, and ServiceInstructions types

Source: https://github.com/zeabur/cli/blob/main/_autodocs/types.md

Defines input and related types for service creation, including CreateServiceInput, MarketplaceItem, PrebuiltItem, GitRepo, and ServiceInstructions.

```go
type CreateServiceInput struct {
	ProjectID string          `json:"projectID" graphql:"projectID"`
	Name      string          `json:"name" graphql:"name"`
	Template  ServiceTemplate `graphql:"template"`
}
type MarketplaceItem struct {
	Code        string `graphql:"code"`
	Description string `graphql:"description"`
	IconURL     string `graphql:"iconURL"`
	Name        string `graphql:"name"`
	NetworkType string `graphql:"networkType"`
}
type PrebuiltItem struct {
	ID          string `graphql:"id"`
	Name        string `graphql:"name"`
	Description string `graphql:"description"`
}
type GitRepo struct {
	Name  string `graphql:"name"`
	Owner string `graphql:"owner"`
	URL   string `graphql:"url"`
	ID    int    `graphql:"id"`
}
type ServiceInstructions struct {
	Instructions []ServiceInstruction `graphql:"instructions"`
}
```

--------------------------------

### zeabur email keys get

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-email.md

Retrieves details for a specific email API key by its ID.

```APIDOC
## zeabur email keys get

### Description
Retrieves details for a specific email API key by its ID.

### Command
`zeabur email keys get`

### Parameters
#### Flags
- **--id** (string) - Required - API key ID
```

--------------------------------

### OnboardZSend

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-zsend-aihub-file.md

Initiates the onboarding process for Z-Send.

```APIDOC
## OnboardZSend

### Description
Initiates the onboarding process for Z-Send.

### Method
GraphQL Mutation

### Parameters
None

### Response
- **ZSendOnboardingStatus** (object) - The updated onboarding status.
```

--------------------------------

### Login with browser using npx zeabur auth login

Source: https://github.com/zeabur/cli/blob/main/README.md

Opens a browser window to log in with your Zeabur account. Requires Node.js installed.

```shell
npx zeabur auth login
```

--------------------------------

### Context and BasicInfo interfaces

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/zcontext.md

Defines the Context interface for managing workspace, project, environment, and service pins, and the BasicInfo interface for basic resource info. ClearAll clears project, environment, and service but leaves workspace intact.

```go
type Context interface {
	GetWorkspace() *Workspace
	SetWorkspace(workspace *Workspace)
	ClearWorkspace()

	GetProject() BasicInfo
	SetProject(project BasicInfo)
	ClearProject()

	GetEnvironment() BasicInfo
	SetEnvironment(environment BasicInfo)
	ClearEnvironment()

	GetService() BasicInfo
	SetService(service BasicInfo)
	ClearService()

	ClearAll()
}

type BasicInfo interface {
	GetID() string
	GetName() string
	Empty() bool
}
```

--------------------------------

### New Client

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-client.md

Creates a new API client instance with an API token.

```APIDOC
## New Client

### Description
Creates a new API client instance using the provided API token.

### Method
Constructor

### Signature
`api.New(token string) *Client`

### Parameters
- **token** (string) - Required - The API token used for authentication.

### Example
```go
client := api.New("zat_...")
```
```

--------------------------------

### Add Tests with Ginkgo Bootstrap and Generate

Source: https://github.com/zeabur/cli/blob/main/docs/development_guide.md

Steps to add tests for a package (e.g., `internal/cmd/auth/login`): bootstrap the suite file and generate the test file.

```shell
cd internal/cmd/auth/login
```

```shell
ginkgo bootstrap
```

```shell
ginkgo generate login
```

--------------------------------

### ProjectAPI interface definition

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-project.md

Defines the ProjectAPI interface with methods for listing, getting, creating, deleting, exporting, and cloning projects, plus region and server queries. The interface is implemented in pkg/api/project.go.

```go
	ProjectAPI interface {
		// ListProjects accepts an optional ownerID (empty = caller's personal
		// projects). For a team workspace pass the team's ObjectID hex.
		ListProjects(ctx context.Context, ownerID string, skip, limit int) (*model.ProjectConnection, error)
		ListAllProjects(ctx context.Context, ownerID string) (model.Projects, error)
		GetProject(ctx context.Context, id string, ownerName string, name string) (*model.Project, error)
		// CreateProject creates a project under the given owner. Empty
		// ownerID means the caller's personal projects.
		CreateProject(ctx context.Context, ownerID, region string, name *string) (*model.Project, error)
		DeleteProject(ctx context.Context, id string) error
		ExportProject(ctx context.Context, id string, environmentID string) (*model.ExportedTemplate, error)

		GetRegions(ctx context.Context) ([]model.Region, error)
		GetServers(ctx context.Context) ([]model.Server, error)
		GetGenericRegions(ctx context.Context) ([]model.GenericRegion, error)

		CloneProject(ctx context.Context, projectID, environmentID, targetRegion string, suspendOldProject bool) (*model.CloneProjectResult, error)
		CloneProjectStatus(ctx context.Context, newProjectID string) (*model.CloneProjectStatusResult, error)
	}
```

--------------------------------

### POST /v2/upload/{upload_id}/prepare

Source: https://github.com/zeabur/cli/blob/main/_autodocs/endpoints.md

Prepares the uploaded zip for deployment. Supports both new project and existing service paths.

```APIDOC
## POST /v2/upload/{upload_id}/prepare

### Description
Prepares the uploaded zip for deployment. Supports both new project and existing service paths.

### Method
POST

### Endpoint
https://api.zeabur.com/v2/upload/{upload_id}/prepare

### Parameters
#### Path Parameters
- **upload_id** (string) - Required - Upload session id

#### Request Body
- **upload_type** (string) - Required - `"new_project"` or `"existing_service"`
- **service_id** (string) - Optional - Service ObjectID hex (required when upload_type is `"existing_service"`)
- **environment_id** (string) - Optional - Environment ObjectID hex (required when upload_type is `"existing_service"`)

### Request Example
{
  "upload_type": "existing_service",
  "service_id": "...",
  "environment_id": "..."
}

### Response
#### Success Response (200 OK)
(No response body documented)

#### Response Example
(No response body example provided)

### Error Response
Error bodies have the shape `{"code": "REQUIRE_PAID_PLAN", "error": "..."}`; `pkg/util.FormatHTTPError` surfaces `error` + `code` when present.
```

--------------------------------

### Go: Resolve project name and environment ID, chain pre-run

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/internal-util.md

Shows three utility calls: GetProjectByName for workspace-aware project resolution, ResolveEnvironmentIDByServiceID for default env resolution, and RunEChain to chain a context-defaulting pre-run before the main RunE. These are used in project get/delete/export, context set, clone, and similar commands.

```go
// workspace-aware project name resolution used by project get/delete/export,
// context set, and clone:
project, err := util.GetProjectByName(f.ApiClient, f.CurrentOwnerID(), f.Config.GetUsername(), name)

// default env resolution for one-environment projects:
envID, err := util.ResolveEnvironmentIDByServiceID(f.ApiClient, serviceID)

// chain a context-defaulting pre-run before the main RunE:
RunE: util.RunEChain(util.DefaultIDNameByContext(fn, &id, &name), mainRun)
```

--------------------------------

### Config interface definition

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/config.md

Defines the public interface for the configuration object. It provides methods to get and set the token string, user nickname, username, and the inner context, as well as a Write method to flush changes to disk.

```go
type Config interface {
	GetTokenString() string // token string is the single token string, it may be set by user or our login function
	SetTokenString(token string)

	GetUser() string // nickname of user
	SetUser(user string)
	GetUsername() string // it is kind like id of user
	SetUsername(username string)

	GetContext() zcontext.Context

	Write() error
}
```

--------------------------------

### Login with token using npx zeabur auth login --token

Source: https://github.com/zeabur/cli/blob/main/README.md

Logs in using a token instead of a browser. Replace <your-token> with your actual token.

```shell
npx zeabur auth login --token <your-token>
```

--------------------------------

### NewEphemeralContext constructor

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/zcontext.md

Creates an in-memory context for the --workspace override. Reads start empty (no fallback to persisted state) and writes go to in-memory fields only, so changes never reach disk. GetWorkspace returns the supplied workspace.

```go
func NewEphemeralContext(workspace *Workspace) Context
```

--------------------------------

### LogAPI interface definition

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-service.md

Defines the LogAPI interface with methods for getting runtime and build logs, and watching runtime and build logs via WebSocket. GetRuntimeLogs requires serviceID and queries runtimeLogs with or without deploymentID. Watch methods subscribe to logReceived events and push into a channel of capacity 100.

```go
	LogAPI interface {
		GetRuntimeLogs(ctx context.Context, serviceID, environmentID, deploymentID string) (model.Logs, error)
		GetBuildLogs(ctx context.Context, deploymentID string) (model.Logs, error)

		WatchRuntimeLogs(ctx context.Context, projectID, serviceID, environmentID, deploymentID string) (<-chan model.Log, error)
		WatchBuildLogs(ctx context.Context, projectID, deploymentID string) (<-chan model.Log, error)
	}
```

--------------------------------

### NewViperContext constructor

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/zcontext.md

Creates a persisted context backed by the shared Viper instance. Reads and writes go to Viper keys, so changes persist on the next config write.

```go
func NewViperContext(viper *viper.Viper) Context
```

--------------------------------

### Error handling patterns in Go consumer code

Source: https://github.com/zeabur/cli/blob/main/_autodocs/errors.md

This snippet shows five common error handling patterns in Go: propagated errors, typed GraphQL errors, SSH exit errors, string-based checks, and HTTP error bodies. It includes examples for 401 detection, server exec exit status, and payment detection.

```go
// 1. Propagated error values (returned as the second element):
project, err := f.ApiClient.GetProject(ctx, id, "", "")
if err != nil {
	return fmt.Errorf("failed to get project: %w", err)
}

// 2. Typed GraphQL errors (401 detection used by login):
var graphqlErrors graphql.Errors
if errors.As(err, &graphqlErrors) &&
	len(graphqlErrors) > 0 &&
	strings.HasPrefix(graphqlErrors[0].Message, "401 Unauthorized") {
	// token expired/invalid → re-login
}

// 3. Typed SSH exit errors (used by `server exec`):
var exitErr *ssh.ExitError
if errors.As(runErr, &exitErr) {
	os.Exit(exitErr.ExitStatus())
}

// 4. String-based checks (used by `server rent` payment detection):
errMsg := err.Error()
if strings.Contains(errMsg, "bind a credit card or recharge credits") ||
   strings.Contains(errMsg, "insufficient balance") {
	// payment required
}

// 5. HTTP error bodies carry a backend code that is already merged
//    into the message by util.FormatHTTPError:
//    "failed to create upload session: Upload size ... exceeds ... (code: REQUIRE_PAID_PLAN, status: 402)"
```

--------------------------------

### Zeabur API client usage in Go

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-client.md

Creates an API client with a token, lists personal projects, creates a project, lists services, and retrieves runtime logs. All methods return (value, error); transport errors are graphql.Errors.

```go
client := api.New("zat_...")          // created per command in PersistentPreRunE
ctx := context.Background()

projects, err := client.ListAllProjects(ctx, "")          // personal workspace
if err != nil { return fmt.Errorf("list projects failed: %w", err) }

proj, err := client.CreateProject(ctx, "", "sfo0", &name) // create under personal
service, err := client.ListAllServices(ctx, proj.ID)

logs, err := client.GetRuntimeLogs(ctx, service.ID, envID, deploymentID)
for log := range client.WatchRuntimeLogs(ctx, proj.ID, service.ID, envID, "") {
	f.Printer.Table(log.Header(), log.Rows())
}
```

--------------------------------

### Project struct with GraphQL tags

Source: https://github.com/zeabur/cli/blob/main/_autodocs/types.md

Defines the Project struct with fields ID, Name, Description, CreatedAt, IconURL, and Region. All fields are required.

```go
type Project struct {
	ID          string `graphql:"_id"`
	Name        string `graphql:"name"`
	Description string `graphql:"description"`
	CreatedAt time.Time `graphql:"createdAt"`
	IconURL string `graphql:"iconURL"`
	Region Region `graphql:"region"`
}
```

--------------------------------

### Run package tests with go test

Source: https://github.com/zeabur/cli/blob/main/CONTRIBUTING.md

Run all tests in a specific package by navigating to the package directory and executing 'go test ./...'.

```bash
cd xxx && go test ./...
```

--------------------------------

### zeabur server catalog

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/commands-server-aihub-template.md

Lists all available providers, regions, and plans for renting a dedicated server. Supports filtering by provider, country, minimum CPU, minimum memory, and GPU availability. Output is JSON only.

```APIDOC
## zeabur server catalog

### Description
Lists all available providers, regions, and plans for renting a dedicated server. Supports filtering by provider, country, minimum CPU, minimum memory, and GPU availability. Output is JSON only.

### Method
CLI command

### Command
`zeabur server catalog`

### Parameters
#### Flags
- `--provider <string>` (string) - Optional - Filter by provider.
- `--country <string>` (string) - Optional - Filter by country.
- `--min-cpu <int>` (int) - Optional - Minimum CPU count.
- `--min-memory <int>` (int) - Optional - Minimum memory in GB.
- `--gpu` (bool) - Optional - Filter for GPU plans.

### Behavior
Fetches providers, then regions per provider, then plans per region concurrently. Applies filters and prunes empty regions/providers. Prints JSON only. First error is returned.

```

--------------------------------

### Deployment model and connection types (model.deployment.go)

Source: https://github.com/zeabur/cli/blob/main/_autodocs/types.md

Defines the Deployment struct with GraphQL and JSON tags, plus DeploymentConnection, DeploymentEdge, and Deployments slice types for paginated queries.

```go
type Deployment struct {
	ID string `graphql:"_id"`
	ProjectID     string `json:"projectID" graphql:"projectID"`
	ServiceID     string `json:"serviceID" graphql:"serviceID"`
	EnvironmentID string `json:"environmentID" graphql:"environmentID"`
	GitProvider   string `json:"gitProvider" graphql:"gitProvider"`
	RepoOwner     string `json:"repoOwner" graphql:"repoOwner"`
	RepoName      string `json:"repoName" graphql:"repoName"`
	Ref           string `json:"ref" graphql:"ref"`
	CommitSHA     string `json:"commitSHA" graphql:"commitSHA"`
	CommitMessage string `json:"commitMessage" graphql:"commitMessage"`
	PlanType string `json:"planType" graphql:"planType"`
	CreatedAt   time.Time `json:"createdAt" graphql:"createdAt"`
	ScheduledAt time.Time `json:"scheduledAt" graphql:"scheduledAt"`
	StartedAt   time.Time `json:"startedAt" graphql:"startedAt"`
	FinishedAt  time.Time `json:"finishedAt" graphql:"finishedAt"`
	Status string `json:"status" graphql:"status"`
}
type DeploymentConnection struct {
	Edges []*DeploymentEdge `json:"edges" graphql:"edges"`
}
type DeploymentEdge struct {
	Node   *Deployment `json:"node" graphql:"node"`
	Cursor string      `json:"cursor" graphql:"cursor"`
}
type Deployments []*Deployment

```

--------------------------------

### ListAllServices

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-client.md

Lists all services in a specified project.

```APIDOC
## ListAllServices

### Description
Lists all services associated with the given project ID.

### Method
GraphQL Query

### Signature
`client.ListAllServices(ctx context.Context, projectID string) ([]Service, error)`

### Parameters
- **ctx** (context.Context) - Required - The context for the request.
- **projectID** (string) - Required - The ID of the project whose services to list.

### Return Value
- **services** ([]Service) - The list of services.
- **error** (error) - An error if the operation failed.

### Example
```go
service, err := client.ListAllServices(ctx, proj.ID)
```
```

--------------------------------

### Constructor New

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/selector.md

Creates a new Selector instance. The `ownerIDFn` must be a closure to resolve the current workspace owner ID at call time, allowing mid-run workspace switches. `nil` results in personal workspace.

```go
func New(client api.Client, log *zap.SugaredLogger, prompter prompt.Prompter, ownerIDFn func() string) Selector
```

--------------------------------

### Run a specific test with ginkgo -focus

Source: https://github.com/zeabur/cli/blob/main/CONTRIBUTING.md

Run a specific test by focusing on a Ginkgo Describe name. Replace 'xxx' with the Describe name.

```bash
cd xxx && ginkgo -focus xxx
```

--------------------------------

### ListAllProjects

Source: https://github.com/zeabur/cli/blob/main/_autodocs/api-reference/api-project.md

Lists all projects for a given owner by walking through pages of 100 items.

```APIDOC
## ListAllProjects

### Description
Lists all projects for a given owner by walking through pages of 100 items.

### Method
GraphQL Query

### Endpoint
`projects` (paginated)

### Parameters
- `ctx` (context.Context) - Required - Context for the request.
- `ownerID` (string) - Required - Owner ID; empty means caller's personal projects.

### Returns
- `model.Projects` - List of all projects.
```
Tokens:
Raw