ags-cli

Agent Git Service workflow CLI for profile-backed repository delivery.

Install

npm install -g @yoyooyoooyoooo/[email protected]
ags-cli --help

The published package currently uses the maintainer npm scope; the executable and workflow surface are generic: ags-cli.

~/.ags-cli is used as the local state home for profiles, token-file references, shims, logs, and cache. The CLI package itself is installed by the package manager, not copied into ~/.ags-cli/lib/ags-cli.

Session env

eval "$(ags-cli env print --profile <profile>)"

Agent sessions may use:

eval "$(ags-cli env print --mode agent --profile <profile>)"

List available profile metadata before activation when the profile name is unknown:

ags-cli profile list --json

The command never reads token content and reports malformed profile files separately. Tokens are referenced by profile metadata and token files; raw token values should not be printed, stored in shell history, pasted into Issues, or extracted through an Agent-driven browser flow. AGS_CLI_PROFILE_DIR is an actual loader input, not diagnostic-only metadata.

PR creation

ags-cli pr create --repo <owner/repo> --head <branch> --base main \
  --title "<issue>: <title>" --body "Multica: <workspace>/<issue>"

ags-cli pr create is the only supported and preferred AGS PR creation write. Agents should invoke it directly; gh pr create exists only as compatibility fallback for existing tools/scripts. In a Multica task session it exchanges the task-scoped mat_ token for External PR link proof and attaches that proof before creating the AGS PR. Task sessions must explicitly trust the active AGS host through MULTICA_EXTERNAL_PR_LINK_TOKEN_ALLOWED_HOSTS, AGS_URL, AGENT_GIT_SERVICE_URL, or AGS_PUBLIC_URL; scheme, host, and effective port must match. A loopback profile endpoint is also accepted when its scheme and effective port exactly match an explicitly trusted public AGS host, covering host-local AGS runtimes without trusting arbitrary remote profile targets. Failure to obtain proof or establish that trust stops creation instead of leaving an unbound PR. The session-local gh shim routes gh pr create through the same implementation. With an active AGS profile, every other ags-cli gh command is rejected before the profile token is read or injected; use ags-cli api and the dedicated ags-cli pr/ci commands instead. Without an AGS profile, ags-cli gh remains an uncredentialed passthrough to the user's normal gh runtime. Direct pull-request creation through either ags-cli api POST /api/v3/repos/<owner>/<repo>/pulls or ags-cli gh api .../pulls is rejected so callers cannot bypass this contract. Pass explicit --title and --body/--body-file; unsupported gh --fill* modes fail rather than inventing PR content.

Legacy profile cutover

From an agent-kit source checkout, preview and apply migration from the former dotenv profile store without printing token values:

node packages/ags-cli/scripts/migrate-legacy-profiles.mjs
node packages/ags-cli/scripts/migrate-legacy-profiles.mjs --apply

The script writes private ~/.ags-cli/profiles/*.yaml metadata and ~/.ags-cli/secrets/*.token files, refuses conflicting targets, and is idempotent. Verify every migrated identity with ags-cli api GET /api/v3/user before moving legacy files to system Trash. Legacy helpers and profile directories are cutover input only; they must not remain in active PATH, runtime custom env, or plugin configuration.

Runtime diagnosis and PR workflow

ags-cli doctor --network --expected-user-kind <human|agent> --json
ags-cli pr resolve --url http://forgejo.imile/<owner>/<repo>/pulls/<forgejo-pr> --target <target> --profile <profile>
ags-cli pr status --repo <owner/repo> --pr <ags-pr> --profile <profile> --json
ags-cli pr verify --repo <owner/repo> --pr <ags-pr> --target <target> --profile <profile> --ci-policy <required|optional>
ags-cli pr close --repo <owner/repo> --pr <ags-pr> --reason "superseded by corrected PR" --profile <profile> --dry-run

doctor --network verifies configured AGS/Forgejo identities without printing token values and rejects unsafe localhost Forgejo fallback for a remote AGS profile. Pass --expected-user-kind agent for Multica Agent sessions and human for member profiles. pr resolve maps Forgejo and AGS numbers by head branch/SHA instead of assuming their numbers match. pr verify, pr resolve, ci runs, ci log, Forgejo PR/run reads, and non-dry-run repo onboard --target <target> calls delegate to the target owner host without recursive SSH. Existing-repo onboarding grants the projection bot and converges its base push whitelist before per-ref seeding; the configured base must converge, while unrelated divergent remote branches are retained and reported instead of blocking onboarding. pr verify emits a top-level readiness summary; explicit optional CI classifies a missing run as no_run_optional, while required CI makes it blocking. pr close closes the AGS-authoritative PR only; run pr resolve afterward to verify projection convergence.

For Agent-authored commits, verify both API identity and commit attribution. The Git credential shim does not rewrite Git author metadata. Use command-scoped author variables rather than changing global Git config:

GIT_AUTHOR_NAME="$AGS_CLI_ACTIVE_LOGIN" \
GIT_AUTHOR_EMAIL="[email protected]" \
GIT_COMMITTER_NAME="$AGS_CLI_ACTIVE_LOGIN" \
GIT_COMMITTER_EMAIL="[email protected]" \
  git commit -m "..."

Existing AGS Agent identities

With a human AGS profile active, list the existing AGS Agent identities bound to that human:

ags-cli identity list --json

Or select the human profile explicitly:

ags-cli identity list --human-profile <human-profile> --json

The command reads GET /api/v3/user/agents from AGS and returns secret-safe identity, token-status, repo-grant, and team-grant summaries. It does not enumerate all service identities, return token values, or claim that an identity is unoccupied by Multica.

Multica Agent name, lane/branch slot, local profile name, and AGS login may differ. The selected Multica write profile must still authenticate an operator-approved existing user_kind=agent identity; a human token is not a lane-agent exception.