Skip to content

README.md

Latest commit

 

History

History
269 lines (203 loc) · 10.1 KB

README.md

File metadata and controls

269 lines (203 loc) · 10.1 KB
Raw

eds — Evolution DevServices CLI for cloud.ru developer tools

eds is a small, agent-friendly command-line client for cloud.ru developer tools products. It currently covers two products:

  • Repo (eds repo) — git repositories in the cloud.
  • Workflow Studio (eds wf) — wires a repository + branch to a deploy pipeline and publishes it.

Installation

From a GitHub Release (recommended)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/cloud-ru/evolution-devservices-cli/main/scripts/install.sh | sudo bash -s -- -b /usr/local/bin/
eds version

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/cloud-ru/evolution-devservices-cli/main/scripts/install.ps1 | iex
eds version

Using Go

go install github.com/cloud-ru/evolution-devservices-cli/cmd/eds@latest
eds version

Configuration

The CLI looks for configuration in this order (later wins):

  1. Built-in defaults: Repo API URL https://devtools.api.cloud.ru/repo/api/v1, git host https://repo.cloud.ru/, Workflow Studio API URL https://devtools.api.cloud.ru/workflow/v1.
  2. File ~/.config/eds/config.json (overridable via EDS_CONFIG or XDG_CONFIG_HOME) — a single platform-level file shared by both products.
  3. Environment variables (see table below).
  4. Per-command flags.

Env vars and flags are namespaced by product for URLs — EDS_REPO_*/--repo-* for Repo, EDS_WF_*/--wf-* for Workflow Studio — except for --api-key/ EDS_API_KEY and --project/EDS_PROJECT_ID, which are shared platform-level settings.

Commands

eds login                                  save credentials to the local config
eds config                                 show effective configuration
eds version                                print the CLI version

eds repo list [--search S] [--sort ...]    list git repositories
eds repo create <name>                     create a repository
eds repo show <id-or-name>                 show repository details
eds repo delete <id-or-name> [--force]     delete a repository
eds repo clone <id-or-name> [dir] [--ssh]  clone via local git CLI
eds repo remote-add <id-or-name> [--name N] [--ssh]  wire an existing local checkout to it (git remote add)

eds wf app create <name> --repository R|--repository-url URL --branch B [--space-id S] [--port N]   create and auto-deploy a Workflow Studio application
eds wf app list [--space-id S]                        list applications
eds wf app show <id>                                  show application details
eds wf app update <id> --branch B [--name N] [--space-id S] [--port N]   update name/branch/space/port
eds wf app delete <id> [--force]                       delete an application
eds wf app deploy <id>                                run the pipeline and publish
eds wf app deployments <id>                           list publish history

eds wf pipeline list                                    list pipelines
eds wf pipeline show <id>                               show pipeline details

eds wf run list [--pipeline-id ID] [--limit N] [--with-config]   list pipeline runs
eds wf run show <id>                                  show a run's status, stages and jobs
eds wf run stop <id>                                  stop a running run

eds wf space list                                     list application spaces
eds wf space create --name <name>                     create an application space
eds wf space show <id>                                show an application space
eds wf space update <id> --name <name>                update an application space
eds wf space delete <id>                              delete an application space

eds wf variable list --pipeline-id <id>               list variables for a pipeline
eds wf variable create <name> <value> --pipeline-id   create a variable
eds wf variable update <name> <value> --pipeline-id     update a variable
eds wf variable delete <name> --pipeline-id             delete a variable

eds wf job list --run-id <id>                         list jobs for a run
eds wf job show <id>                                  show job details
eds wf job stop <id>                                  stop a running job
eds wf job logs <id>                                  get logs for a job

Login

eds login --api-key "$EDS_API_KEY" --project <project-id>
eds login --repo-api-url https://devtools.dev.api.internal.cloud.ru/repo/api/v1 \
          --api-key "$EDS_API_KEY" --project <project-id>

For an AI agent

The CLI is designed to be safely scripted. Recommended pattern:

export EDS_API_KEY="..."
export EDS_PROJECT_ID="..."

# List repos as JSON, pipe into jq
eds repo list --json | jq '.repositories[].name'

# Create a repo, capture the new id
eds repo create demo --json | jq -r '.id'

# Inspect
eds repo show demo --json | jq '.clone.https'

# Clone (uses the system's git)
eds repo clone demo ./work/demo

All commands return exit code 0 on success, non-zero on failure, and write errors to stderr in a single line:

Error: api error 404: {"error_msg":"404 Not Found"}

See skills/eds/SKILL.md for the canonical Agent Skills description that can be attached to an AI agent.

Workflow Studio (deploy & publish)

Workflow Studio is a "developer tools" product on cloud.ru: it wires a repository + branch to a deploy pipeline. An application is that wiring; running the application's pipeline (a deployment) publishes it and produces a live URL. This is the CLI's main "vibe-coded a site, now ship it" path — eds repo gets your code hosted, eds wf app publishes it.

export EDS_API_KEY="..."
export EDS_PROJECT_ID="..."

# 1. Create the repo and push code (see "File upload / push" below)
eds repo create my-site
eds repo clone my-site && cd my-site
# ...add code + Dockerfile...
git add . && git commit -m "init" && git push origin main

# 2. Wire it to a Workflow Studio application. Creating it auto-triggers the
#    first deploy — you don't need a separate `deploy` call right after create.
APP_ID=$(eds wf app create my-site --repository "$REPO_ID" --branch main --json | jq -r '.id')

# 3. Poll until it's actually live. Check application.status (not just run
#    status) because "publishing" can last well after the run already reports
#    "done".
for i in $(seq 1 20); do
  STATUS=$(eds wf app show "$APP_ID" --json | jq -r '.status')
  echo "status: $STATUS"
  [ "$STATUS" = "running" ] || [ "$STATUS" = "error" ] && break
  sleep 15
done
URL=$(eds wf app deployments "$APP_ID" --json | jq -r '.deployments[0].url')
echo "url: $URL"

If a deployment fails, drill into the failing job's logs:

eds wf app show "$APP_ID" --json | jq -r '.run.stages[].jobs[] | select(.status=="failed") | .id' \
  | xargs -I{} eds wf job logs {}

eds wf run and eds wf job are the lower-level primitives behind eds wf app show — use them directly when you need to inspect or control a particular run (e.g. eds wf run stop) or stream job logs (eds wf job logs).

File upload / push

This CLI does not implement a custom upload path. To push code, use the standard git workflow after eds repo clone:

eds repo clone demo
cd demo
git add . && git commit -m "init" && git push origin main

git push works out of the box because eds repo clone already embedded the API key as basic-auth credentials in origin's URL (see .git/config) — no git credential helper or OS keychain is involved. Note this means the API key sits in plaintext in that repo's .git/config; treat the clone directory with the same care as the key itself.

If the code already exists locally (no eds repo clone involved) and you just created the remote repository, use eds repo remote-add instead of a plain git remote add to get the same embedded authentication:

eds repo create demo
cd path/to/existing/local/repo
eds repo remote-add demo
git push -u origin main

--ssh is the one exception: it depends on the host's SSH public key being registered separately (not handled by this CLI), so it still needs whatever ambient SSH setup the environment provides.

Distribution / publishing

Releases are published on GitHub Releases.

Manual release (Makefile)

# cross-compile everything into ./dist/ + sha256 checksums
make release

# tag, then cut the release with the built artifacts
git tag v0.2.0 && git push origin v0.2.0
gh release create v0.2.0 dist/* --generate-notes

GoReleaser release (recommended)

This project includes a GoReleaser configuration (.goreleaser.yaml) that mirrors the Makefile build matrix and produces the same artifacts:

# Local snapshot build (no tag required, produces ./dist/)
make goreleaser-build

# Full release — requires a git tag; builds, checksums, and uploads to GitHub
# (draft release; publish manually or enable auto-publish in .goreleaser.yaml)
git tag v0.2.0 && git push origin v0.2.0
make goreleaser-release

Environment variables

Variable Description
EDS_PROJECT_ID Default project ID (shared across products)
EDS_REPO_API_URL Repo product API base URL (overrides config)
EDS_API_KEY API key used for both products (X-API-KEY)
EDS_REPO_GIT_HOST Repo product git smart-HTTP host
EDS_WF_API_URL Workflow Studio product API base URL (overrides config)
EDS_CONFIG Path to config file (overrides default)
XDG_CONFIG_HOME Respected when locating the config file
AWS_ENDPOINT_URL S3-compatible endpoint for make upload (optional mirror)

Contributing

See CONTRIBUTING.md for the development setup and PR process, and CODE_OF_CONDUCT.md for community guidelines. Report security issues to opensource@cloud.ru rather than a public issue.

License

Apache License 2.0 — see LICENSE.