agentclash-cli-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# AgentClash CLI Setup

## Purpose
Configure an AgentClash CLI session that can reach the intended backend, authenticate safely, resolve the right workspace, and pass `agentclash doctor` before a user starts authoring packs or running evals.

## Use When
- A user asks to install, authenticate, verify, or repair AgentClash CLI access.
- A coding agent needs AgentClash access but does not have the AgentClash source repo.
- A user needs to switch workspaces, save a default workspace, or create project-local `.agentclash.yaml` config.
- A CLI command fails because API URL, token, organization, workspace, or saved config precedence is unclear.
- CI needs a non-interactive setup path with `AGENTCLASH_TOKEN`.

## Do Not Use When
- The CLI is already configured and the task is to run an eval or inspect a scorecard.
- The user needs to author challenge pack YAML; use `agentclash-challenge-pack-yaml-author` after setup passes.
- The user is making a release decision or CI gate from completed runs; use `agentclash-ci-release-gate`.
- The task requires changing AgentClash CLI source code rather than using the CLI.

## Inputs Needed
- Backend target: hosted production, local development, or self-hosted.
- Whether the CLI is installed as `agentclash` or run from source with `go run .` inside `cli/`.
- Whether browser/device login is acceptable, or whether `AGENTCLASH_TOKEN` must be used.
- Organization ID if `workspace list` cannot infer one from saved config.
- Workspace ID, workspace slug/name, or permission to choose one interactively with `agentclash link`.
- Whether the command should mutate saved user config under `~/.config/agentclash/config.yaml`.
- Whether the current repository should get project-local `.agentclash.yaml` config with `agentclash init`.

## Environment
Use hosted production by default:

```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"
```

Use a local backend only when the user is explicitly running the API server locally:

```bash
export AGENTCLASH_API_URL="http://localhost:8080"
```

For CI or other non-interactive shells, provide a token through the environment instead of running browser login:

```bash
export AGENTCLASH_TOKEN="<token>"
export AGENTCLASH_WORKSPACE="<workspace-id>"
```

Do not print token values in chat, logs, docs, or committed files.

## Config And Precedence
API URL resolution:

```text
--api-url > AGENTCLASH_API_URL > saved user config > default
```

The source-build default is `http://localhost:8080`. Released CLI builds stamp the production default at release time, but skills should still set `AGENTCLASH_API_URL="https://api.agentclash.dev"` explicitly for hosted workflows so copied commands behave the same in source and released builds.

Workspace resolution:

```text
--workspace / -w > AGENTCLASH_WORKSPACE > project .agentclash.yaml > saved user config
```

Organization resolution for commands that need an org:

```text
AGENTCLASH_ORG > project .agentclash.yaml > saved user config
```

Auth token resolution:

```text
AGENTCLASH_TOKEN > stored CLI credentials
```

Saved user config lives at:

```text
~/.config/agentclash/config.yaml
```

Project-local config lives in `.agentclash.yaml` and is discovered by walking up from the current directory. It can store `workspace_id` and `org_id`.

## Procedure
1. Choose the backend. For normal hosted work, export `AGENTCLASH_API_URL="https://api.agentclash.dev"` first.
2. Verify the CLI is callable with `agentclash version` or, from the repo `cli/` directory, `go run . version`.
3. Authenticate. Prefer `agentclash auth login --device` for remote shells; use `AGENTCLASH_TOKEN` for CI.
4. Check the authenticated identity with `agentclash auth status`.
5. Select a workspace with `agentclash link` for the guided flow, or `agentclash workspace use <workspace-id>` when the ID is already known. Both commands write saved user config.
6. If this repository should carry its own workspace binding, run `agentclash init --workspace-id <workspace-id> --org-id <organization-id>` from the project root.
7. Run `agentclash doctor` to verify install, auth, workspace, challenge-pack visibility, deployment visibility, and baseline readiness.
8. Report the effective backend, auth state, workspace, doctor result, and the next command the user should run.

## Commands
Hosted production, interactive setup:

```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"
agentclash version
agentclash auth login --device
agentclash auth status
agentclash link
agentclash doctor
```

Hosted production when the workspace ID is already known:

```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"
agentclash auth login --device
agentclash workspace use <workspace-id>
agentclash doctor
```

Workspace discovery when an organization must be explicit:

```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"

From agentclash/agentclash, MIT.

More from agentclash/agentclash