develop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Local Development with GuaraCloud

基于GuaraCloud的本地开发

Project Linking

项目关联

Link your working directory to a GuaraCloud project so commands automatically know which project/service to target:

bash

guara link                                    # Interactive picker
guara link --project my-app --service api     # Direct link

This creates

.guara.json

in the current directory:

json

{
  "project": "my-app",
  "service": "api"
}

The CLI walks upward from the current directory to find this file. Add

.guara.json

.gitignore

if it contains developer-specific choices.

Remove a link:

bash

guara unlink

将你的工作目录与GuaraCloud项目关联，这样命令就会自动知晓目标项目/服务：

bash

guara link                                    # 交互式选择器
guara link --project my-app --service api     # 直接关联

这会在当前目录下创建

.guara.json

文件：

json

{
  "project": "my-app",
  "service": "api"
}

CLI会从当前目录向上查找该文件。如果

.guara.json

包含开发者专属配置，建议将其添加到

.gitignore

中。

取消关联：

bash

guara unlink

Remote Shell (exec)

远程Shell（exec）

Open an interactive shell in a running service container:

bash

guara exec                          # Default shell (/bin/sh)
guara exec --shell /bin/bash        # Use bash

Run a one-shot command:

bash

guara exec -- ls -la /app
guara exec -- cat /etc/hostname
guara exec -- env                   # Check runtime env vars
guara exec -- node -e "console.log(process.env.DATABASE_URL)"

JSON mode buffers output and returns structured result:

bash

guara exec --json -- whoami

在运行中的服务容器中打开交互式Shell：

bash

guara exec                          # 默认Shell（/bin/sh）
guara exec --shell /bin/bash        # 使用bash

执行一次性命令：

bash

guara exec -- ls -la /app
guara exec -- cat /etc/hostname
guara exec -- env                   # 查看运行时环境变量
guara exec -- node -e "console.log(process.env.DATABASE_URL)"

JSON模式会缓存输出并返回结构化结果：

bash

guara exec --json -- whoami

Returns: { "exitCode": 0, "output": "node\n", "command": ["whoami"] }

返回结果: { "exitCode": 0, "output": "node\n", "command": ["whoami"] }


**Requirements:** Service must be running with at least one healthy pod. If you get "No ready pods available", start the service first: `guara services start`.


**注意事项：** 服务必须处于运行状态且至少有一个健康的pod。如果出现“No ready pods available”提示，请先启动服务：`guara services start`。

Port Forwarding (proxy)

端口转发（proxy）

Forward a local port to the service's container port:

bash

guara proxy                         # Random local port assigned
guara proxy --local-port 8080       # Forward localhost:8080 -> container

Use cases:

Connect to a database running in the service
Test API endpoints locally
Debug with local tools

Press Ctrl+C to stop. Only one TCP connection at a time per proxy session.

将本地端口转发到服务的容器端口：

bash

guara proxy                         # 自动分配随机本地端口
guara proxy --local-port 8080       # 将localhost:8080转发到容器端口

适用场景：

连接到服务中运行的数据库
本地测试API接口
使用本地工具进行调试

按Ctrl+C停止转发。每个代理会话同一时间仅支持一个TCP连接。

Log Streaming

日志流

View recent logs:

bash

guara logs                          # Last 100 lines
guara logs --lines 500              # More lines

Stream in real time:

bash

guara logs --follow                 # Polls every 2.5s
guara logs -f --level error         # Only errors, streaming

Filter logs:

bash

guara logs --level error            # By level: trace|debug|info|warn|error|fatal
guara logs --since 1h               # Last hour (also: 30m, 2d, 90s)
guara logs --search "connection refused"  # Text search
guara logs --since 2h --level warn --search "timeout"  # Combined

Time range query:

bash

guara logs --since 2026-04-01T00:00:00Z --until 2026-04-01T12:00:00Z

查看近期日志：

bash

guara logs                          # 最近100行日志
guara logs --lines 500              # 查看更多行数

实时流式查看日志：

bash

guara logs --follow                 # 每2.5秒轮询一次
guara logs -f --level error         # 仅流式查看错误日志

过滤日志：

bash

guara logs --level error            # 按级别过滤：trace|debug|info|warn|error|fatal
guara logs --since 1h               # 查看最近1小时的日志（支持：30m, 2d, 90s）
guara logs --search "connection refused"  # 文本搜索
guara logs --since 2h --level warn --search "timeout"  # 组合过滤

时间范围查询：

bash

guara logs --since 2026-04-01T00:00:00Z --until 2026-04-01T12:00:00Z

Environment Management

环境管理

List current env vars (values masked):

bash

guara env list
guara env list --json               # Full values in JSON

Set variables:

bash

guara env set KEY=value
guara env set KEY1=val1 KEY2=val2   # Multiple at once
guara env set NPM_TOKEN=xxx --build # Available during Docker build

Remove variables:

bash

guara env unset KEY
guara env unset KEY1 KEY2

Important:

env set

and

env unset

trigger a rolling restart of the service. The new process picks up the updated environment.

列出当前环境变量（值会被掩码处理）：

bash

guara env list
guara env list --json               # 以JSON格式查看完整值

设置环境变量：

bash

guara env set KEY=value
guara env set KEY1=val1 KEY2=val2   # 同时设置多个变量
guara env set NPM_TOKEN=xxx --build # 该变量在Docker构建阶段可用

删除环境变量：

bash

guara env unset KEY
guara env unset KEY1 KEY2

重要提示：

env set

和

env unset

会触发服务的滚动重启。新的进程会加载更新后的环境变量。

CLI Configuration

CLI配置

bash

guara config list                   # Show api-url and api-key status
guara config get api-url            # Get specific value
guara config set api-url https://api.guaracloud.com
guara config reset                  # Reset to defaults

bash

guara config list                   # 查看api-url和api-key状态
guara config get api-url            # 获取特定配置值
guara config set api-url https://api.guaracloud.com
guara config reset                  # 重置为默认配置

Tips

小贴士

Use
--json
for scripting. All commands support
```
--json
```
for structured output and
```
--quiet
```
for minimal output (IDs only).
Use
--yes
to skip prompts in CI/CD or scripted workflows.

Env var overrides are useful in CI:

GUARA_API_KEY

GUARA_PROJECT

GUARA_SERVICE

let you skip

guara login

and

guara link

脚本化场景使用
--json
参数：所有命令都支持
```
--json
```
参数以返回结构化输出，以及
```
--quiet
```
参数以返回极简输出（仅ID）。
在CI/CD或脚本工作流中使用
--yes
跳过提示。
环境变量覆盖在CI中很实用：
```
GUARA_API_KEY
```
、
```
GUARA_PROJECT
```
、
```
GUARA_SERVICE
```
可让你跳过
```
guara login
```
和
```
guara link
```
步骤。