CLI Setup Skill

1---
2name: agentclash-cli-setup
3description: Use when configuring the AgentClash CLI, authenticating with device login or tokens, selecting a workspace, saving default config with link, creating project config with init, resolving API URL precedence, or diagnosing CLI access against production, local, or self-hosted backends.
4metadata:
5  agentclash.role: setup
6  agentclash.version: "1"
7  agentclash.requires_cli: "true"
8---
9
10# AgentClash CLI Setup
11
12## Purpose
13Configure 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.
14
15## Use When
16- A user asks to install, authenticate, verify, or repair AgentClash CLI access.
17- A coding agent needs AgentClash access but does not have the AgentClash source repo.
18- A user needs to switch workspaces, save a default workspace, or create project-local `.agentclash.yaml` config.
19- A CLI command fails because API URL, token, organization, workspace, or saved config precedence is unclear.
20- CI needs a non-interactive setup path with `AGENTCLASH_TOKEN`.
21
22## Do Not Use When
23- The CLI is already configured and the task is to run an eval or inspect a scorecard.
24- The user needs to author challenge pack YAML; use `agentclash-challenge-pack-yaml-author` after setup passes.
25- The user is making a release decision or CI gate from completed runs; use `agentclash-ci-release-gate`.
26- The task requires changing AgentClash CLI source code rather than using the CLI.
27
28## Inputs Needed
29- Backend target: hosted production, local development, or self-hosted.
30- Whether the CLI is installed as `agentclash` or run from source with `go run .` inside `cli/`.
31- Whether browser/device login is acceptable, or whether `AGENTCLASH_TOKEN` must be used.
32- Organization ID if `workspace list` cannot infer one from saved config.
33- Workspace ID, workspace slug/name, or permission to choose one interactively with `agentclash link`.
34- Whether the command should mutate saved user config under `~/.config/agentclash/config.yaml`.
35- Whether the current repository should get project-local `.agentclash.yaml` config with `agentclash init`.
36
37## Environment
38Use hosted production by default:
39
40```bash
41export AGENTCLASH_API_URL="https://api.agentclash.dev"
42```
43
44Use a local backend only when the user is explicitly running the API server locally:
45
46```bash
47export AGENTCLASH_API_URL="http://localhost:8080"
48```
49
50For CI or other non-interactive shells, provide a token through the environment instead of running browser login:
51
52```bash
53export AGENTCLASH_TOKEN="<token>"
54export AGENTCLASH_WORKSPACE="<workspace-id>"
55```
56
57Do not print token values in chat, logs, docs, or committed files.
58
59## Config And Precedence
60API URL resolution:
61
62```text
63--api-url > AGENTCLASH_API_URL > saved user config > default
64```
65
66The 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.
67
68Workspace resolution:
69
70```text
71--workspace / -w > AGENTCLASH_WORKSPACE > project .agentclash.yaml > saved user config
72```
73
74Organization resolution for commands that need an org:
75
76```text
77AGENTCLASH_ORG > project .agentclash.yaml > saved user config
78```
79
80Auth token resolution:
81
82```text
83AGENTCLASH_TOKEN > stored CLI credentials
84```
85
86Saved user config lives at:
87
88```text
89~/.config/agentclash/config.yaml
90```
91
92Project-local config lives in `.agentclash.yaml` and is discovered by walking up from the current directory. It can store `workspace_id` and `org_id`.
93
94## Procedure
951. Choose the backend. For normal hosted work, export `AGENTCLASH_API_URL="https://api.agentclash.dev"` first.
962. Verify the CLI is callable with `agentclash version` or, from the repo `cli/` directory, `go run . version`.
973. Authenticate. Prefer `agentclash auth login --device` for remote shells; use `AGENTCLASH_TOKEN` for CI.
984. Check the authenticated identity with `agentclash auth status`.
995. 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.
1006. If this repository should carry its own workspace binding, run `agentclash init --workspace-id <workspace-id> --org-id <organization-id>` from the project root.
1017. Run `agentclash doctor` to verify install, auth, workspace, challenge-pack visibility, deployment visibility, and baseline readiness.
1028. Report the effective backend, auth state, workspace, doctor result, and the next command the user should run.
103
104## Commands
105Hosted production, interactive setup:
106
107```bash
108export AGENTCLASH_API_URL="https://api.agentclash.dev"
109agentclash version
110agentclash auth login --device
111agentclash auth status
112agentclash link
113agentclash doctor
114```
115
116Hosted production when the workspace ID is already known:
117
118```bash
119export AGENTCLASH_API_URL="https://api.agentclash.dev"
120agentclash auth login --device
121agentclash workspace use <workspace-id>
122agentclash doctor
123```
124
125Workspace discovery when an organization must be explicit:
126
127```bash
128export AGENTCLASH_API_URL="https://api.agentclash.dev"
129agentclash workspace list --org <organization-id>
130agentclash workspace get <workspace-id>
131agentclash workspace use <workspace-id>
132```
133
134Project-local config for a repository:
135
136```bash
137agentclash init --workspace-id <workspace-id> --org-id <organization-id>
138```
139
140CI or non-interactive setup:
141
142```bash
143export AGENTCLASH_API_URL="https://api.agentclash.dev"
144export AGENTCLASH_TOKEN="<token>"
145export AGENTCLASH_WORKSPACE="<workspace-id>"
146agentclash doctor --json
147```
148
149Local development from the CLI module:
150
151```bash
152cd cli
153export AGENTCLASH_API_URL="http://localhost:8080"
154go run . auth login --device
155go run . link
156go run . doctor
157```
158
159One-off backend override without changing saved config:
160
161```bash
162agentclash --api-url http://localhost:8080 doctor
163```
164
165Introspect the full command tree, flags, and stable exit codes as
166machine-readable JSON (no auth required) — prefer this over scraping `--help`:
167
168```bash
169agentclash schema --json
170```
171
172## Expected Output
173- `auth login --device` prints a verification URL or confirms an existing valid login.
174- `auth status` shows the authenticated user and accessible organization/workspace counts.
175- `link` saves the selected workspace and organization in user config and prints the next suggested command. It does not write `.agentclash.yaml`.
176- `workspace use <workspace-id>` validates access and saves `default_workspace`; it also saves `default_org` when the workspace details include an organization ID.
177- `init --workspace-id <workspace-id> --org-id <organization-id>` writes project-local `.agentclash.yaml` in the current directory.
178- `doctor` prints the effective API URL, workspace, setup checks, and suggested next steps. In JSON mode, `ready: true` means no `warn` or `fail` checks remain.
179
180## Failure Modes
181- `AGENTCLASH_TOKEN is set but could not be validated`: the environment token is present and takes precedence, but it is wrong for this backend. Unset or replace `AGENTCLASH_TOKEN`, then rerun `agentclash auth login --device` or `agentclash auth status`.
182- `Not logged in. No API token is configured.`: run `agentclash auth login --device` for interactive work, or set `AGENTCLASH_TOKEN` for CI.
183- Commands unexpectedly hit `http://localhost:8080`: set `AGENTCLASH_API_URL="https://api.agentclash.dev"` or pass `--api-url`; source builds default to localhost.
184- `organization ID required`: pass `--org <organization-id>` or set a default organization through `agentclash link`, `agentclash workspace use`, or config.
185- `no workspace specified`: run `agentclash link`, pass `--workspace <workspace-id>`, set `AGENTCLASH_WORKSPACE`, or create project config with `agentclash init`.
186- `Workspace <id> is not accessible`: the saved or env workspace does not belong to the current token/backend. Run `agentclash link` or update `AGENTCLASH_WORKSPACE`.
187- `doctor` reports no challenge packs: setup is valid, but the workspace needs `agentclash challenge-pack init`, `validate`, and `publish` before evals are useful.
188- `doctor` reports no deployments: setup is valid, but an agent deployment must be created before starting evals.
189- `doctor` reports no baseline: this is advisory on a fresh workspace; set one after the first completed eval with `agentclash baseline set`.
190
191## Safety Notes
192- Never paste, print, or commit `AGENTCLASH_TOKEN` or provider secrets.
193- Ask before changing saved user config when the user is sharing a machine or switching production workspaces.
194- Prefer `--api-url` for one-off local/self-hosted checks so saved production config is not accidentally changed.
195- Prefer `doctor --json` in automation because it returns a machine-readable `ready` field and exits non-zero when setup warnings remain.
196- Run read-only commands (`auth status`, `workspace list`, `doctor`) before write or publish commands.
197
198## Report Back Format
199```text
200Backend: <effective API URL>
201Auth: <ok | action needed> (<source: AGENTCLASH_TOKEN | stored credentials | none>)
202Workspace: <workspace-id or none>
203Doctor: <ready | warnings> - <short check summary>
204Next command: <single recommended command>
205Notes: <config precedence, local override, or token caveat if relevant>
206```
207
208## Related Skills
209- `agentclash-hub` — load first for full workflow map and UI links
210- `agentclash-quickstart` — readiness checks after auth
211- `agentclash-workspace-admin` — org/workspace CRUD and team membership
212- `agentclash-eval-runner`
213
214## Related Docs
215- `/docs-md/getting-started/quickstart`
216- `/docs-md/guides/use-with-ai-tools`
217- `/docs-md/reference/cli`
218- `/docs-md/reference/config`
219- `/docs-md/agent-skills`