Render CLI

https://github.com/render-oss/cli
Admin
Render CLI is a command-line interface tool that enables developers to manage Render platform...
Tokens:824,974
Snippets:5,604
Trust Score:9.3
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### skills.Install

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/skills.md

Example of installing skills with a tool filter and skill filter.

```APIDOC
## skills.Install

### Description
Installs skills into tools based on the provided input. Returns the installed skills and tools.

### Method
Install

### Parameters
#### Input Fields
- **ToolFilter** (string) - Required - Filter for the tool to install skills into.
- **SkillFilter** ([]string) - Required - List of skill names to install.
- **Scope** (Scope) - Optional - Scope of the installation (e.g., project or global).
- **RepoRoot** (string) - Optional - Root of the repository for project-scope installation.
- **DryRun** (bool) - Optional - If true, performs a dry run without actually installing.

### Request Example
```go
res, err := skills.Install(skills.InstallInput{
	ToolFilter:  "Claude Code",
	SkillFilter: []string{"render"},
})
```

### Response
#### Success Response
- **Skills** ([]Skill) - List of installed skills.
- **Tools** ([]Tool) - List of tools that received skills.
- **DryRun** (bool) - Indicates if the operation was a dry run.

#### Response Example
```go
fmt.Printf("installed %d skills into %d tools\n", len(res.Skills), len(res.Tools))
```

### Error Handling
- Returns an error if the installation fails.
- For project-scope installs, returns an error if the repository root cannot be determined.
```

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

### Example

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/storage.md

This example demonstrates how to create a storage service and use it to upload and download files.

```APIDOC
## Example

```go
svc, err := storage.NewService(c, storage.ServiceConfig{
	Region:  "oregon",
	OwnerId: "ws-abc",
})
if err != nil {
	return err
}

uploaded, err := svc.Upload(ctx, "backups/db.sql", "./db.sql")
if err != nil {
	return err
}
fmt.Println("uploaded", uploaded.SizeBytes, "bytes")

var buf bytes.Buffer
downloaded, err := svc.Download(ctx, "backups/db.sql", &buf)
if err != nil {
	return err
}
fmt.Println("downloaded", downloaded.SizeBytes, "bytes; hash match:", buf.Len() == int(uploaded.SizeBytes))
```
```

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

### skills.GetRepoRoot

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/skills.md

Example of getting the repository root for project-scope installation.

```APIDOC
## skills.GetRepoRoot

### Description
Retrieves the root directory of the current git repository. Used for project-scope installations.

### Method
GetRepoRoot

### Parameters
None.

### Request Example
```go
repoRoot, err := skills.GetRepoRoot()
```

### Response
#### Success Response
- **repoRoot** (string) - The absolute path to the repository root.

#### Response Example
```go
repoRoot, err := skills.GetRepoRoot()
```

### Error Handling
- Returns an error if the current directory is not inside a git repository.
```

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

### Install skills with tool and skill filters

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/skills.md

Installs skills matching the tool filter "Claude Code" and the skill filter "render". Prints the number of installed skills and tools. Returns an error if installation fails.

```go
res, err := skills.Install(skills.InstallInput{
	ToolFilter:  "Claude Code",
	SkillFilter: []string{"render"},
})
if err != nil {
	return err
}
fmt.Printf("installed %d skills into %d tools\n", len(res.Skills), len(res.Tools))

```

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

### Example: list and deploy service

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/repositories.md

Example usage of the Dependencies container: creates a default client, initializes dependencies, lists services by name, and deploys the first service found. Prints the deployment ID.

```go
c, err := client.NewDefaultClient()
if err != nil {
	return err
}
deps := dependencies.New(c)

services, err := deps.ServiceRepo().ListServices(ctx, &client.ListServicesParams{
	Name: &client.NameParam{"my-api"},
})
if err != nil {
	return err
}
if len(services) == 0 {
	return errors.New("no service found")
}
deploy, err := deps.ServiceRepo().DeployService(ctx, services[0])
if err != nil {
	return err
}
fmt.Println("deploy started:", deploy.Id)
```

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

### Example: local dev mode

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/storage.md

This example shows how to configure the storage service for local development mode, using a local base path instead of cloud storage.

```APIDOC
## Example: local dev mode

```go
svc, err := storage.NewService(c, storage.ServiceConfig{
	Local:    true,
	Region:   "oregon",
	BasePath: "./.render-storage",
})
if err != nil {
	return err
}
if _, err := svc.Delete(ctx, "temp/file.txt"); err != nil {
	return err
} // deletes ./.render-storage/<workspace>/oregon/temp/file.txt
```
```

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

### ListAll usage example

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

Example usage of ListAll to fetch all services, passing the context, parameters, and a listPage function. Returns an error if the operation fails.

```go
services, err := client.ListAll(ctx, params, serviceRepo.listPage)
if err != nil {
	return nil, err
}
```

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

### Project-scope install with dry run and error handling

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/skills.md

Performs a dry-run project-scope install. Requires a git repository; GetRepoRoot returns an error if not in one. Prints the number of skills that would be installed when DryRun is true.

```go
repoRoot, err := skills.GetRepoRoot()
if err != nil {
	return fmt.Errorf("project-scope install requires a git repository: %w", err)
}

res, err := skills.Install(skills.InstallInput{
	Scope:    skills.ScopeProject,
	RepoRoot: repoRoot,
	DryRun:   true,
})
if err != nil {
	return err
}
if res.DryRun {
	fmt.Println("would install:", len(res.Skills))
}

```

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

### cli.yaml configuration example

Source: https://github.com/render-oss/cli/blob/main/_autodocs/configuration.md

Example cli.yaml configuration file. The file is created on first Config.Persist() with mode 0o600; a missing file loads as {version: 1} with no error. The RENDER_API_KEY environment variable overrides the api.key field.

```yaml
version: 1
workspace: "ws-abc123def"        # active workspace ID
workspace_name: "acme"           # display name
user_email: "user@example.com"   # optional
project_filter: "prj-abc"        # optional listing filter
project_name: "My Project"       # optional
api:                             # embedded APIConfig
  key: "rnd_..."                 # OAuth access token (RENDER_API_KEY wins)
  expires_at: 1710000000
  host: "https://api.render.com/v1/"
  refresh_token: "..."           # OAuth refresh token
dashboard_url: "https://dashboard.render.com"
```

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

### Example: ListResources

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/resource.md

Creates a default resource service and lists resources filtered by environment ID, printing type, ID, and name.

```go
rs, err := resource.NewDefaultResourceService()
if err != nil {
	return err
}

resources, err := rs.ListResources(ctx, resource.ResourceParams{
	EnvironmentIDs:  []string{"evm-abc"},
	IncludePreviews: false,
})
if err != nil {
	return err
}
for _, r := range resources {
	fmt.Println(r.Type(), r.ID(), r.Name())
}
```

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

### ServerHandler struct and NewHandler/Start functions

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/workflows.md

Defines the ServerHandler struct and the NewHandler and Start functions for the local HTTP server. Start mounts a chi router under /v1 with routes for tasks, task runs, logs, and WebSocket/SSE subscriptions.

```go
type ServerHandler struct {
	coordinator *orchestrator.Coordinator
	taskStore   *store.TaskStore
	logStore    *logs.LogStore
	upgrader    *websocket.Upgrader
}

func NewHandler(coordinator *orchestrator.Coordinator, taskStore *store.TaskStore, logStore *logs.LogStore, upgrader *websocket.Upgrader) *ServerHandler
func Start(handler *ServerHandler, port int) (*http.Server, error)
```

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

### GET /postgres

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists Postgres instances.

```APIDOC
## GET /postgres

### Description
Lists Postgres instances.

### Method
GET

### Endpoint
/postgres

### Response
#### Success Response (200)
- **postgres** (array) - List of Postgres instances.

```

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

### Example: sending an execution result

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/analytics.md

Shows how to create a Sender and send an ExecutionResult. Send is best-effort and never returns errors.

```go
sender := analytics.New(apiClient)

result := command.ExecutionResult{
	CommandPath:    "render services list",
	CompletionKind: command.CompletionKindSuccess,
	ExitCode:       0,
	StartedAt:      time.Now(),
	OutputFormat:   &command.JSON,
}

// Best-effort; never returns errors
sender.Send(result, os.Stderr)
```

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

### Run a local workflow HTTP server

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/workflows.md

Initializes the task store, coordinator, and API handler, then starts an HTTP server on port 8080. Returns an error if startup fails and defers closing the server.

```go
taskStore := store.NewTaskStore()
coordinator := orchestrator.NewCoordinator(ctx, taskStore, sdkExec, socketTracker, serverFactory, statusReporter)
handler := apiserver.NewHandler(coordinator, taskStore, logStore, upgrader)

server, err := apiserver.Start(handler, 8080)
if err != nil {
	return err
}
defer server.Close()
```

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

### Cobra command factory with dependency injection

Source: https://github.com/render-oss/cli/blob/main/AGENTS.md

Illustrates the recommended command construction pattern: a factory function `newPgGetCmd` accepts dependencies and returns a `*cobra.Command`, then a setup function registers it. Avoid package-global singletons and init-time registration.

```go
// cmd/pgget.go
func newPgGetCmd(deps *dependencies.Dependencies) *cobra.Command {
	cmd := &cobra.Command{
		Use:   "get <postgresID|postgresName>",
		Short: "Get a Postgres database",
		RunE: func(cmd *cobra.Command, args []string) error {
			return deps.PostgresService().Get(cmd.Context(), args[0])
		},
	}
	return cmd
}

// cmd/root.go
func setupPGCommands(earlyAccess *cobra.Command, deps *dependencies.Dependencies) {
	earlyAccess.AddCommand(newPgCmd(newPgGetCmd(deps)))
}
```

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

### Example: restart by ID prefix (error handling)

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/resource.md

Restarts a service by ID prefix, then demonstrates error handling for cron jobs and unknown resource types.

```go
err := rs.RestartResource(ctx, "srv-xyz")
if err != nil {
	return err
}

if err := rs.RestartResource(ctx, "crn-xyz"); err != nil {
	fmt.Println("cannot restart:", err) // "cron jobs cannot be restarted"
}

if _, err := rs.GetResource(ctx, "unknown-id"); err != nil {
	return err // "unknown resource type"
}
```

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

### Instance repository API (pkg/instance)

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/repositories.md

Instance repository API. Backs `GET /services/{serviceId}/instances`. Source: `pkg/instance/repo.go`.

```go
func NewRepo(c *client.ClientWithResponses) *Repo
func (r *Repo) ListInstancesForService(ctx context.Context, serviceID string) ([]*client.ServiceInstance, error)
```

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

### GET /users

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Gets the current user.

```APIDOC
## GET /users

### Description
Gets the current user.

### Method
GET

### Endpoint
/users

```

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

### GET /tasks

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists tasks.

```APIDOC
## GET /tasks

### Description
Lists tasks.

### Method
GET

### Endpoint
/tasks

```

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

### GET /tasks/{taskId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Gets a specific task.

```APIDOC
## GET /tasks/{taskId}

### Description
Gets a specific task.

### Method
GET

### Endpoint
/tasks/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the task.

```

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

### GET /workflows/{workflowId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Gets a specific workflow.

```APIDOC
## GET /workflows/{workflowId}

### Description
Gets a specific workflow.

### Method
GET

### Endpoint
/workflows/{workflowId}

### Parameters
#### Path Parameters
- **workflowId** (string) - Required - The ID of the workflow.

```

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

### Define cfg package constants and version variables

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

Defines the repository URL and installation instructions URL constants, along with the Version variable (defaulting to "dev") and an unexported osInfo variable. Version is populated at build time via ldflags.

```go
const (
	RepoURL                     = "https://api.github.com/repos/render-oss/cli"
	InstallationInstructionsURL = "https://render.com/docs/cli#1-install-or-upgrade"
)

var (
	Version = "dev"
	osInfo  string
)
```

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

### Seed renderapi fake server with owner, project, and Postgres in Go tests

Source: https://github.com/render-oss/cli/blob/main/AGENTS.md

Use this Go test setup to seed the `renderapi` fake server with an owner, workspace, project, environment, and a Postgres resource. It sets the `RENDER_WORKSPACE` environment variable and demonstrates the preferred pattern for command tests that hit the API, as shown in `cmd/pglist_test.go`.

```go
server := renderapi.NewServer(t)
server.Owners.Add(renderapi.NewOwner(client.Owner{Id: activeWorkspaceID}))
t.Setenv("RENDER_WORKSPACE", activeWorkspaceID)

project := server.CreateProject(
    renderapi.ProjectAttrs{Name: "My Project", OwnerId: activeWorkspaceID},
    renderapi.EnvAttrs{Name: "production"},
)
server.Postgres.Add(renderapi.NewPostgres(client.PostgresDetail{
    Name:          "prod-db",
    Owner:         client.Owner{Id: activeWorkspaceID},
    EnvironmentId: pointers.From(project.Env("production").Id),
}))
```

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

### Async command pattern in Update

Source: https://github.com/render-oss/cli/blob/main/pkg/tui/AGENTS.md

Example of using commands for asynchronous I/O in Update(). Never block in Update(); return a tea.Cmd instead. The fetchData function returns a tea.Cmd that performs the I/O and returns a message.

```go
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        return m, m.fetchData()  // Return command, don't block
    case DataLoadedMsg:
        m.data = msg.Data
        return m, nil
    }
    return m, nil
}

func (m Model) fetchData() tea.Cmd {
    return func() tea.Msg {
        data, err := m.repo.List()
        if err != nil {
            return ErrorMsg{Err: err}
        }
        return DataLoadedMsg{Data: data}
    }
}
```

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

### User repository API (pkg/user)

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/repositories.md

User repository API. Backs `GET /users` and is used by `render whoami`. Source: `pkg/user/repo.go`.

```go
func NewRepo(client *client.ClientWithResponses) *Repo
func (r *Repo) CurrentUser(ctx context.Context) (*client.User, error)
```

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

### GET /workflowversions/{workflowVersionId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Gets a specific workflow version.

```APIDOC
## GET /workflowversions/{workflowVersionId}

### Description
Gets a specific workflow version.

### Method
GET

### Endpoint
/workflowversions/{workflowVersionId}

### Parameters
#### Path Parameters
- **workflowVersionId** (string) - Required - The ID of the workflow version.

```

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

### GET /task-runs/{taskRunId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Gets a specific task run.

```APIDOC
## GET /task-runs/{taskRunId}

### Description
Gets a specific task run.

### Method
GET

### Endpoint
/task-runs/{taskRunId}

### Parameters
#### Path Parameters
- **taskRunId** (string) - Required - The ID of the task run.

```

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

### GET /workflows

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists workflows.

```APIDOC
## GET /workflows

### Description
Lists workflows.

### Method
GET

### Endpoint
/workflows

```

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

### Test CLI against local dev API with tilt and environment variables

Source: https://github.com/render-oss/cli/blob/main/AGENTS.md

Use this to test the CLI against a local development API. Start the API with `tilt up api`, verify it with `curl -k https://api.localhost.render.com:8443/health`, then set `RENDER_HOST` and `RENDER_API_KEY` environment variables before running CLI commands like `./render services list`.

```bash
# Start API
tilt up api
curl -k https://api.localhost.render.com:8443/health

# Configure CLI
export RENDER_HOST="https://api.localhost.render.com:8443/v1/"
export RENDER_API_KEY="your-api-key"
./render services list
```

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

### Struct-tagged command example

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/command.md

Shows a createInput struct with cli tags and a runCreate function that parses command arguments into the struct. Validate returns an error if --name is missing in non-interactive mode.

```go
type createInput struct {
	Name          string   `cli:"name"`
	Plan          *string  `cli:"plan"`
	Region        *string  `cli:"region"`
	EnvironmentID *string  `cli:"environment-id"`
	EnvVars       []string `cli:"env-var"`
	ServiceID     string   `cli:"arg:0"`
}

func (i *createInput) Validate(interactive bool) error {
	if interactive {
		return nil
	}
	if i.Name == "" {
		return errors.New("--name is required in non-interactive mode")
	}
	return nil
}

func runCreate(cmd *cobra.Command, args []string) error {
	var input createInput
	if err := command.ParseCommand(cmd, args, &input); err != nil {
		return err
	}
	// input is populated from --name, --plan, ... and arg 0
	return doHTTPCreate(input)
}
```

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

### GET /webhooks

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists webhooks.

```APIDOC
## GET /webhooks

### Description
Lists webhooks.

### Method
GET

### Endpoint
/webhooks

```

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

### Query logs with ListLogs

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/logs.md

Example of querying logs with ListLogs. Requires an active workspace ID (OwnerId) and a resource filter. Prints each log's timestamp and message.

```go
import (
	lclient "github.com/render-oss/cli/pkg/client/logs"
	"github.com/render-oss/cli/pkg/logs"
)

repo := logs.NewLogRepo(c, apiCfg)

page, err := repo.ListLogs(ctx, &client.ListLogsParams{
	OwnerId:  "ws-abc", // required: active workspace
	Resource: lclient.LogFilterResource{"srv-abc"},
})
if err != nil {
	return err
}
for _, l := range page.Logs {
	fmt.Println(l.Timestamp, l.Message)
}
```

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

### GET /postgres/{postgresId}/query/sizes

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists sizes for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/query/sizes

### Description
Lists sizes for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/query/sizes

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **sizes** (array) - List of sizes.

```

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

### scaffold package: Language enum and NextStep/TemplateMetadata types

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/workflows.md

Defines the Language enum and types for scaffolding metadata. ParseLanguage maps common aliases to Python or TypeScript. SetupCommand uses python3 (or python on Windows) and creates a .venv, normalizing pip3 to pip to avoid PEP 668 errors. LocalRepoOverride returns the env var (RENDER_WORKFLOWS_TEMPLATES_PYTHON or RENDER_WORKFLOWS_TEMPLATES_TYPESCRIPT) that overrides the examples repo.

```go
type Language string

const (
	Python     Language = "python"
	TypeScript Language = "node"
)

func (l Language) DisplayName() string
func ExamplesRepoURL(lang Language) string
func ParseLanguage(s string) (Language, error) // "python"/"py" → Python; "node"/"typescript"/"ts" → TypeScript; else error

var repoURLs = map[Language]string{ ... }          // installable examples repos
var localRepoEnvVars = map[Language]string{ ... }  // Python: RENDER_WORKFLOWS_TEMPLATES_PYTHON; TypeScript: RENDER_WORKFLOWS_TEMPLATES_TYPESCRIPT
func LocalRepoOverride(lang Language) string       // env var overriding the examples repo

func SetupCommand(lang Language) string                      // Python: "python3 -m venv .venv && source .venv/bin/activate"
func DepsInstallCommand(lang Language, buildCmd string) string // Python: wrap with venv pip
func LocalBuildCommand(lang Language, buildCmd string) string
func LocalStartCommand(lang Language, startCmd string) string

type NextStep struct {
	Label   string `yaml:"label"`
	Command string `yaml:"command,omitempty"`
	Hint    string `yaml:"hint,omitempty"`
}

type TemplateMetadata struct {
	Name          string `yaml:"name"`
	DirName       string `yaml:"-"`
	Description   string `yaml:"description"`
	Default       bool   `yaml:"default"`
	WorkflowsRoot string `yaml:"workflowsRoot,omitempty"`
	ClientRoot    string `yaml:"clientRoot,omitempty"`
	RenderBuildCommand string `yaml:"renderBuildCommand,omitempty"`
	// ... more template.yaml fields
}
```

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

### GET /postgres/{postgresId}/query/processes

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists processes for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/query/processes

### Description
Lists processes for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/query/processes

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **processes** (array) - List of processes.

```

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

### Create authenticated client and list services

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

Creates an authenticated client with NewDefaultClient and lists services for a given owner ID. It checks for errors from the response via ErrorFromResponse and returns nil when the JSON200 list is empty. The example uses the OwnerIdParam with a placeholder workspace ID.

```go
import "github.com/render-oss/cli/pkg/client"

func servicesList(ctx context.Context) ([]*client.Service, error) {
	c, err := client.NewDefaultClient()
	if err != nil {
		return nil, err
	}
	resp, err := c.ListServicesWithResponse(ctx, &client.ListServicesParams{
		OwnerId: &client.OwnerIdParam{"ws-abc"},
	})
	if err != nil {
		return nil, err
	}
	if err := client.ErrorFromResponse(resp); err != nil {
		return nil, err
	}
	if resp.JSON200 == nil || len(*resp.JSON200) == 0 {
		return nil, nil
	}
	services := make([]*client.Service, 0, len(*resp.JSON200))
	for _, swc := range *resp.JSON200 {
		services = append(services, &swc.Service)
	}
	return services, nil
}
```

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

### GET /notification-settings/overrides

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists notification overrides.

```APIDOC
## GET /notification-settings/overrides

### Description
Lists notification overrides.

### Method
GET

### Endpoint
/notification-settings/overrides

### Response
#### Success Response (200)
- **overrides** (array) - List of notification overrides.

```

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

### GET /task-runs

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists task runs.

```APIDOC
## GET /task-runs

### Description
Lists task runs.

### Method
GET

### Endpoint
/task-runs

```

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

### GET /maintenance

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists maintenance runs.

```APIDOC
## GET /maintenance

### Description
Lists maintenance runs.

### Method
GET

### Endpoint
/maintenance

```

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

### GET /workflowversions

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists workflow versions.

```APIDOC
## GET /workflowversions

### Description
Lists workflow versions.

### Method
GET

### Endpoint
/workflowversions

```

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

### GET /webhooks/{webhookId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves a specific webhook.

```APIDOC
## GET /webhooks/{webhookId}

### Description
Retrieves a specific webhook.

### Method
GET

### Endpoint
/webhooks/{webhookId}

### Parameters
#### Path Parameters
- **webhookId** (string) - Required - The ID of the webhook.

```

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

### GET /postgres/{postgresId}/export

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists exports for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/export

### Description
Lists exports for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/export

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **exports** (array) - List of exports.

```

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

### GET /postgres/{postgresId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves a specific Postgres instance.

```APIDOC
## GET /postgres/{postgresId}

### Description
Retrieves a specific Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **postgres** (object) - Postgres instance details.

```

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

### GET /objects/{ownerId}/{region}/{key}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Returns a presigned download URL for an object.

```APIDOC
## GET /objects/{ownerId}/{region}/{key}

### Description
Returns a presigned download URL for an object.

### Method
GET

### Endpoint
/objects/{ownerId}/{region}/{key}

### Parameters
#### Path Parameters
- **ownerId** (string) - Required - The owner identifier.
- **region** (string) - Required - The region identifier.
- **key** (string) - Required - The object key.

### Response
#### Success Response (200)
- **downloadUrl** (string) - Presigned download URL.

```

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

### GET /owners

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists owners with an optional name filter.

```APIDOC
## GET /owners

### Description
Lists owners with an optional name filter.

### Method
GET

### Endpoint
/owners

### Parameters
#### Query Parameters
- **Name** (string) - Optional - Filter by owner name.

### Response
#### Success Response (200)
- **owners** (array) - List of owners.

```

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

### GET /notification-settings/owners/{ownerId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves notification settings for an owner.

```APIDOC
## GET /notification-settings/owners/{ownerId}

### Description
Retrieves notification settings for an owner.

### Method
GET

### Endpoint
/notification-settings/owners/{ownerId}

### Parameters
#### Path Parameters
- **ownerId** (string) - Required - The owner identifier.

### Response
#### Success Response (200)
- **settings** (object) - Notification settings.

```

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

### GET /owners/{ownerId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves a specific owner.

```APIDOC
## GET /owners/{ownerId}

### Description
Retrieves a specific owner.

### Method
GET

### Endpoint
/owners/{ownerId}

### Parameters
#### Path Parameters
- **ownerId** (string) - Required - The owner identifier.

### Response
#### Success Response (200)
- **owner** (object) - Owner details.

```

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

### GET /postgres/{postgresId}/query/top-queries

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists top queries for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/query/top-queries

### Description
Lists top queries for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/query/top-queries

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **topQueries** (array) - List of top queries.

```

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

### GET /metrics-stream/{ownerId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves the metrics stream for an owner.

```APIDOC
## GET /metrics-stream/{ownerId}

### Description
Retrieves the metrics stream for an owner.

### Method
GET

### Endpoint
/metrics-stream/{ownerId}

### Parameters
#### Path Parameters
- **ownerId** (string) - Required - The owner identifier.

### Response
#### Success Response (200)
- **metricsStream** (object) - Metrics stream configuration.

```

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

### Upload and download with storage.NewService

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/storage.md

Shows how to create a storage service with a region and owner ID, upload a local file, then download it into a buffer and verify the byte count matches. Requires a valid client and context.

```go
svc, err := storage.NewService(c, storage.ServiceConfig{
	Region:  "oregon",
	OwnerId: "ws-abc",
})
if err != nil {
	return err
}

uploaded, err := svc.Upload(ctx, "backups/db.sql", "./db.sql")
if err != nil {
	return err
}
fmt.Println("uploaded", uploaded.SizeBytes, "bytes")

var buf bytes.Buffer
downloaded, err := svc.Download(ctx, "backups/db.sql", &buf)
if err != nil {
	return err
}
fmt.Println("downloaded", downloaded.SizeBytes, "bytes; hash match:", buf.Len() == int(uploaded.SizeBytes))
```

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

### GET /postgres/{postgresId}/parameter-overrides/available

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists available parameter overrides for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/parameter-overrides/available

### Description
Lists available parameter overrides for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/parameter-overrides/available

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **availableOverrides** (array) - List of available parameter overrides.

```

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

### GET /notification-settings/overrides/services/{serviceId}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves notification overrides for a service.

```APIDOC
## GET /notification-settings/overrides/services/{serviceId}

### Description
Retrieves notification overrides for a service.

### Method
GET

### Endpoint
/notification-settings/overrides/services/{serviceId}

### Parameters
#### Path Parameters
- **serviceId** (string) - Required - The service identifier.

### Response
#### Success Response (200)
- **overrides** (object) - Notification overrides for the service.

```

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

### GET /objects/{ownerId}/{region}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists objects in a region for an owner.

```APIDOC
## GET /objects/{ownerId}/{region}

### Description
Lists objects in a region for an owner.

### Method
GET

### Endpoint
/objects/{ownerId}/{region}

### Parameters
#### Path Parameters
- **ownerId** (string) - Required - The owner identifier.
- **region** (string) - Required - The region identifier.

### Response
#### Success Response (200)
- **objects** (array) - List of object metadata.

```

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

### GET /owners/{ownerId}/members

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves members of an owner.

```APIDOC
## GET /owners/{ownerId}/members

### Description
Retrieves members of an owner.

### Method
GET

### Endpoint
/owners/{ownerId}/members

### Parameters
#### Path Parameters
- **ownerId** (string) - Required - The owner identifier.

### Response
#### Success Response (200)
- **members** (array) - List of members.

```

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

### GET /postgres/{postgresId}/credentials

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists database users for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/credentials

### Description
Lists database users for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/credentials

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **users** (array) - List of database users.

```

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

### GET /maintenance/{maintenanceRunID}

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves a specific maintenance run.

```APIDOC
## GET /maintenance/{maintenanceRunID}

### Description
Retrieves a specific maintenance run.

### Method
GET

### Endpoint
/maintenance/{maintenanceRunID}

### Parameters
#### Path Parameters
- **maintenanceRunID** (string) - Required - The ID of the maintenance run.

```

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

### GET /postgres/{postgresId}/parameter-overrides

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists parameter overrides for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/parameter-overrides

### Description
Lists parameter overrides for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/parameter-overrides

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **overrides** (array) - List of parameter overrides.

```

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

### GET /postgres/{postgresId}/connection-info

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves connection information for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/connection-info

### Description
Retrieves connection information for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/connection-info

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **connectionInfo** (object) - Connection details.

```

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

### GET /owners/{ownerId}/audit-logs

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists audit logs for an owner.

```APIDOC
## GET /owners/{ownerId}/audit-logs

### Description
Lists audit logs for an owner.

### Method
GET

### Endpoint
/owners/{ownerId}/audit-logs

### Parameters
#### Path Parameters
- **ownerId** (string) - Required - The owner identifier.

### Response
#### Success Response (200)
- **auditLogs** (array) - List of audit logs.

```

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

### GET /postgres/{postgresId}/query/table-scans

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists table scans for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/query/table-scans

### Description
Lists table scans for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/query/table-scans

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **tableScans** (array) - List of table scans.

```

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

### Tail logs with error handling

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/logs.md

Example of tailing logs with TailLogs and handling events. Checks for log records, terminal errors (prints to stderr and returns), and status updates. After the channel closes, inspects ctx.Err() for cancellation reason.

```go
events := repo.TailLogs(ctx, &client.ListLogsParams{
	OwnerId:  "ws-abc",
	Resource: lclient.LogFilterResource{"srv-abc"},
})

for ev := range events {
	switch {
	case ev.Log != nil:
		fmt.Println(ev.Log.Timestamp, ev.Log.Message)
	case ev.Err != nil:
		fmt.Fprintln(os.Stderr, "tail failed:", ev.Err)
		return ev.Err
	default:
		fmt.Fprintln(os.Stderr, "status:", ev.Status)
	}
}

if err := ctx.Err(); err != nil {
	fmt.Fprintln(os.Stderr, "tail stopped:", err)
	return err
}
```

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

### GET /organizations/{orgId}/audit-logs

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists audit logs for an organization.

```APIDOC
## GET /organizations/{orgId}/audit-logs

### Description
Lists audit logs for an organization.

### Method
GET

### Endpoint
/organizations/{orgId}/audit-logs

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.

### Response
#### Success Response (200)
- **auditLogs** (array) - List of audit logs.

```

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

### GET /webhooks/{webhookId}/events

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Lists events for a specific webhook.

```APIDOC
## GET /webhooks/{webhookId}/events

### Description
Lists events for a specific webhook.

### Method
GET

### Endpoint
/webhooks/{webhookId}/events

### Parameters
#### Path Parameters
- **webhookId** (string) - Required - The ID of the webhook.

```

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

### GET /postgres/{postgresId}/recovery

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Retrieves recovery information for a Postgres instance.

```APIDOC
## GET /postgres/{postgresId}/recovery

### Description
Retrieves recovery information for a Postgres instance.

### Method
GET

### Endpoint
/postgres/{postgresId}/recovery

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **recoveryInfo** (object) - Recovery details.

```

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

### GET /v1/logs

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/logs.md

One-shot log query via `GET /v1/logs`. Returns the parsed `Logs200Response` or the `client.ErrorFromResponse` mapped error.

```APIDOC
## [GET] /v1/logs

### Description
One-shot log query via `GET /v1/logs`. Returns the parsed `Logs200Response` or the `client.ErrorFromResponse` mapped error.

### Method
GET

### Endpoint
/v1/logs

### Parameters
#### Query Parameters
- **OwnerId** (string) - Required - Active workspace ID.
- **Resource** (LogFilterResource) - Required - Resource filter, e.g., `{"srv-abc"}`.

### Request Example
```go
repo := logs.NewLogRepo(c, apiCfg)
page, err := repo.ListLogs(ctx, &client.ListLogsParams{
	OwnerId:  "ws-abc", // required: active workspace
	Resource: lclient.LogFilterResource{"srv-abc"},
})
```

### Response
#### Success Response (200)
- **Logs** (array of `client/logs.Log`) - List of log records.

#### Response Example
```go
for _, l := range page.Logs {
	fmt.Println(l.Timestamp, l.Message)
}
```
```

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

### GET /task-runs/events

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Streams task run events via Server-Sent Events (SSE).

```APIDOC
## GET /task-runs/events

### Description
Streams task run events via Server-Sent Events (SSE).

### Method
GET

### Endpoint
/task-runs/events

```

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

### Create a Postgres database with postgres.NewService

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/datastores.md

Creates a Postgres database using the postgres service. The input specifies the database name and plan, with HighAvailability set to nil. On success, prints the created database ID along with project and environment names.

```go
svc := postgres.NewService(postgresRepo, environmentRepo, projectRepo, resolver)

created, err := svc.Create(ctx, postgres.CreatePostgresInput{
	Name:     "prod-db",
	Plan:     "free",
	HighAvailability: nil,
})
if err != nil {
	return err
}
fmt.Printf("created %s in project %s / env %s\n", created.Postgres.Id, created.Project.Name, created.Environment.Name)

```

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

### Programmatic configuration with config.Load and Persist

Source: https://github.com/render-oss/cli/blob/main/_autodocs/configuration.md

Loads configuration from ~/.render/cli.yaml, sets the workspace, and persists changes. GetHost and GetAPIKey read from environment variables with defaults.

```go
// Programmatic configuration
cfg, err := config.Load()                      // ~/.render/cli.yaml
cfg.Workspace = "ws-new"
if err := cfg.Persist(); err != nil { ... }

host := cfg.GetHost()                          // RENDER_HOST or default
key := cfg.GetAPIKey()                         // RENDER_API_KEY
```

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

### Create a sandbox and exec a command

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/sandbox.md

Creates a sandbox with a 1c-1g plan in Oregon and a 3600-second timeout, then streams the output of the command 'echo hi' to stdout. The callback prints the sandbox state on creation and the exec output stream. Returns a command exit error with the exit code on success.

```go
svc := sandbox.NewService(sandbox.NewRepo(client))

sb, err := svc.Create(ctx, sandbox.CreateInput{
	Plan:    "1c-1g",
	Region:  "oregon",
	Timeout: 3600,
}, func(s *sandboxclient.Sandbox) {
	fmt.Println("sandbox state:", s.Status)
})
if err != nil {
	return err
}

exitCode, err := svc.ExecStream(ctx, sb.Id, "echo hi", func(ev *sandbox.ExecOutputEvent) {
	if ev.Stream == sandbox.ExecOutputStreamStdout {
		fmt.Print(ev.Data)
	}
})
if err != nil {
	return err
}
return command.NewExitError(exitCode, nil)
```

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

### Constructors for Service

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/resource.md

NewDefaultResourceService builds a full stack with default client and repos; NewResourceService takes explicit service and repo dependencies.

```go
func NewDefaultResourceService() (*Service, error)
// Builds a full stack: client.NewDefaultClient() + repos + services + resolver.

func NewResourceService(
	serviceService *service.Service,
	postgresService *postgres.Service,
	keyValueService *keyvalue.Service,
	environmentRepo *environment.Repo,
	projectRepo *project.Repo,
	workflowService *workflow.Service,
) *Service
```

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

### POST /postgres

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Creates a new Postgres instance.

```APIDOC
## POST /postgres

### Description
Creates a new Postgres instance.

### Method
POST

### Endpoint
/postgres

### Response
#### Success Response (200)
- **postgres** (object) - Created Postgres instance.

```

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

### Load config, resolve workspace ID, and store OAuth tokens

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

Shows how to load the Render CLI configuration, resolve the active workspace ID (with env override precedence), and store OAuth tokens via config.SetAPIConfig. Exits with an error message if no workspace is set.

```go
cfg, err := config.Load()
if err != nil {
	return err
}
fmt.Println("workspace:", cfg.Workspace, cfg.WorkspaceName)

// Resolve the active workspace ID (env override wins)
workspaceID, err := config.WorkspaceID()
if errors.Is(err, config.ErrNoWorkspace) {
	fmt.Fprintln(os.Stderr, "run: render workspace set <name|ID>")
	os.Exit(1)
}

// Store OAuth tokens
if err := config.SetAPIConfig(config.APIConfig{
	Key:          token.AccessToken,
	RefreshToken: token.RefreshToken,
	ExpiresAt:    time.Now().Add(time.Duration(token.ExpiresIn) * time.Second).Unix(),
}); err != nil {
	return err
}
```

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

### Dashboard

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

Functions for getting and setting the dashboard URL.

```APIDOC
## DashboardURL

### Description
Returns the dashboard URL. If the config file is unreadable or unset, it returns `https://dashboard.render.com`.

### Function Signature
`func DashboardURL() string`

### Parameters
None.

### Returns
- `string` - The dashboard URL.

### Example
```go
url := config.DashboardURL()
fmt.Println(url)
```
```

```APIDOC
## SetDashboardURL

### Description
Parses the given URL, clears its path, and persists the updated dashboard URL.

### Function Signature
`func SetDashboardURL(u string) error`

### Parameters
- `u` (string) - The dashboard URL to set.

### Returns
- `error` - An error if parsing or persisting fails.

### Example
```go
if err := config.SetDashboardURL("https://dashboard.render.com"); err != nil {
    log.Fatal(err)
}
```
```

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

### POST /postgres/{postgresId}/replication

Source: https://github.com/render-oss/cli/blob/main/_autodocs/endpoints.md

Sets up replication for a Postgres instance.

```APIDOC
## POST /postgres/{postgresId}/replication

### Description
Sets up replication for a Postgres instance.

### Method
POST

### Endpoint
/postgres/{postgresId}/replication

### Parameters
#### Path Parameters
- **postgresId** (string) - Required - The Postgres instance identifier.

### Response
#### Success Response (200)
- **status** (string) - Replication setup status.

```

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

### Plan catalog helpers: PlanValues, PlanOption, PlanOptions

Source: https://github.com/render-oss/cli/blob/main/_autodocs/api-reference/datastores.md

Provides plan catalog helpers: PlanValues returns the list of plan strings, PlanOption defines the {value,label} shape, and PlanOptions returns the available options. Source: pkg/keyvalue/create.go:122-160.

```go
func PlanValues() []string
type PlanOption struct{ Value string; Label string } // shape: {value,label}
func PlanOptions() []PlanOption
```

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

### NewClientWithResponses constructor

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

Constructs a ClientWithResponses by creating a low-level Client with the given server and options, returning an error if creation fails.

```go
func NewClientWithResponses(server string, opts ...ClientOption) (*ClientWithResponses, error) {
	client, err := NewClient(server, opts...)
	if err != nil {
		return nil, err
	}
	return &ClientWithResponses{client}, nil
}
```
Tokens:
Raw