@evolvingmachines/evolve 0.0.65 → 0.0.67

package/skills/evolve-evals/references/cli-reference/job.md

@@ -0,0 +1,198 @@
+---
+title: "evolve job"
+description: "Inspect results, compare runs, and control or repeat evaluations."
+---
+
+Start with the job ID printed by `evolve run`, or find it in the list. Examples below use `$JOB_ID` for that ID.
+
+```bash
+evolve job list
+evolve job show "$JOB_ID"
+evolve job trials "$JOB_ID"
+```
+
+## Inspect results
+
+### Jobs
+
+```bash
+evolve job list --search hello
+evolve job list --kind all --scope org
+evolve job show "$JOB_ID" --json
+```
+
+| Option for `job list` | Meaning |
+| --- | --- |
+| `--search <text>` | Match job names and dataset names. |
+| `--kind <job\|check\|all>` | Evaluations, task checks, or both. Default `job`. |
+| `--scope <my\|shared\|org>` | Which records to list. Default `my`. |
+
+`job show` accepts one or more IDs. With `--json`, one ID returns an object; several return an array.
+
+### Trials
+
+```bash
+evolve job trials "$JOB_ID" --status INFRASTRUCTURE_ERROR,SCORING_ERROR
+evolve job trials "$JOB_ID" --dataset harbor-examples
+```
+
+| Option for `job trials` | Meaning |
+| --- | --- |
+| `--status <statuses>` | Comma-separated trial statuses. |
+| `--dataset <name>` | Select one dataset in the job. |
+
+Statuses: `QUEUED`, `RUNNING`, `SCORING`, `SCORED`, `SCORING_ERROR`, `INFRASTRUCTURE_ERROR`, `BUDGET`, `INDETERMINATE`, `CANCELLED`.
+
+Open an individual result with [`evolve trial show`](/cli-reference/trial).
+
+### Tasks
+
+```bash
+evolve job tasks "$JOB_ID"
+```
+
+One row per task: trial count, statuses, reward, spend, and available task-check information.
+
+`job list`, `job trials`, and `job tasks` accept the shared [paging and formatting options](/cli-reference/index#list-options): `--limit`, `--cursor`, `--columns`, `--quiet`, `--no-trunc`, and `--no-headers`.
+
+A `COMPLETED` job can include failed trials. Inspect the trial statuses as well as the aggregate score.
+
+## Compare jobs
+
+Supply two to ten job IDs.
+
+```bash
+evolve job compare "$JOB_ID" "$OTHER_JOB_ID"
+```
+
+## Search traces
+
+Search across the job's trial traces. `$JOB_ID` comes from `job list` or `run`.
+
+```bash
+evolve job grep "$JOB_ID" 'permission denied'
+evolve job grep "$JOB_ID" 'permission denied' --type tool_call --json
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--type <event-type>` | Match only this exact event type. |
+| `-l`, `--limit <n>` | Trial match groups per page. Default `50`, maximum `200`. |
+| `--cursor <cursor>` | Continue from the returned `nextCursor`. |
+
+## Stop work
+
+### Whole job
+
+```bash
+evolve job cancel "$JOB_ID"
+```
+
+Request cancellation. The returned job may still be winding down.
+
+### One dataset
+
+```bash
+evolve job stop "$JOB_ID" --dataset harbor-examples
+```
+
+Stop that dataset's trials while keeping the rest of the job. `--dataset <name>` is required.
+
+Output separates stopped trials, already-terminal trials, and missing IDs. If a batch fails, the partial report names how many outcomes remain unreported.
+
+For individual trials, use [`trial stop`](/cli-reference/trial#stop-a-trial).
+
+## Run again
+
+Each command creates a new linked job. It leaves the source results intact.
+
+| Command | Work repeated |
+| --- | --- |
+| `evolve job resume "$JOB_ID"` | Failed or stopped trials selected by the resume policy. |
+| `evolve job retry "$JOB_ID"` | All trials of a settled source job. |
+| `evolve job retry "$JOB_ID" --failed-only` | Trials in `SCORING_ERROR`, `INFRASTRUCTURE_ERROR`, `BUDGET`, or `INDETERMINATE`. |
+| `evolve job retry "$JOB_ID" --trial "$TRIAL_ID"` | Exactly the selected settled trial. Repeat `--trial` for more. |
+| `evolve job regrade "$JOB_ID"` | The recorded verifier, using stored inputs. No replacement verifier. |
+
+### Selection options and requirements
+
+**Resume** accepts `-f, --filter-error-type <type>`. Repeat it to select exception types.
+
+**Retry** accepts either `--failed-only` or `-t, --trial <id>`, not both. Copy full trial IDs from `evolve job trials "$JOB_ID"`; these flags do not expand prefixes. Explicit settled trials can be retried while other trials in the source job are still running.
+
+**Regrade** accepts `--status <s1,s2,...>` and `--task <name>`. It requires eligible stored verifier inputs; shared-verifier, multi-step, and judge-backed trials cannot be regraded through this command. See [Trials](/core-concepts/trials).
+
+Uploaded jobs cannot be resumed, retried, or regraded. Their original execution ran outside Evolve.
+
+Start a new evaluation with `evolve job start` or its shorter form, [`evolve run`](/cli-reference/run).
+
+## Download results
+
+```bash
+evolve job download "$JOB_ID" -o results/
+```
+
+```text
+results/
+└── job-<id>/
+    ├── config.json
+    ├── result.json
+    ├── evolve.json          Evolve's record
+    └── <trial folders>/
+```
+
+| Option | Meaning |
+| --- | --- |
+| `-o`, `--output-dir <dir>` | Parent directory. Default: current directory. |
+| `--overwrite` | Allow replacing an existing job folder. |
+
+The download uses the Harbor job layout, with additional `evolve.json` records.
+
+## Share results
+
+Only the creator can manage a job's shares.
+
+```bash Create access
+evolve job share "$JOB_ID" --link
+evolve job share "$JOB_ID" --email colleague@example.com
+```
+
+```bash Inspect or remove access
+evolve job shares "$JOB_ID"
+evolve job unshare "$JOB_ID" --link
+evolve job unshare "$JOB_ID" --email colleague@example.com
+```
+
+Both `share` and `unshare` require `--link`, repeatable `--email <address>`, or both. Email sharing sends the recipient a link. Revoking a link disables it; enabling sharing later creates a new link.
+
+See [Sharing](/core-concepts/sharing) for access rules.
+
+## Read an upload's progress
+
+[`evolve upload`](/cli-reference/upload) prints an import ID before the imported job is ready.
+
+```bash
+evolve job imports --status RUNNING
+evolve job import "$IMPORT_ID" --watch
+```
+
+| Command | Options |
+| --- | --- |
+| `job imports` | Shared list options; `--status <QUEUED\|RUNNING\|COMPLETED\|FAILED>`. |
+| `job import <id>` | `--watch` to follow it to a job or failure. Use the full import ID. |
+
+`job import --watch --json` prints one final job or error document.
+
+## Delete a job
+
+```bash
+evolve job delete "$JOB_ID"
+```
+
+The command asks before permanent deletion. For noninteractive use, pass `-y` or `--yes`.
+
+**Warning:**
+
+Deleting a job removes its stored trials, traces, analyses, and files. Only the creator can delete it, and the job must be eligible for deletion.
+
+[Global options](/cli-reference/index#global-options) apply to every command.

package/skills/evolve-evals/references/cli-reference/run.md

@@ -0,0 +1,187 @@
+---
+title: "evolve run"
+description: "Choose tasks and agents, set limits, and launch an evaluation."
+---
+
+Start a hosted job. `evolve job start` accepts exactly the same options.
+
+```bash
+evolve run \
+  -d harbor-examples@1.0 \
+  -i hello-world \
+  -a codex -m gpt-5.6-luna \
+  --max-trial-spend 0.30 \
+  --max-retries 0 \
+  --watch
+```
+
+```text
+  Selected tasks
+× Agent/model combinations
+× Attempts
+= Trials
+```
+
+Without `--watch`, the command returns after the job is accepted. Keep the printed job ID to [inspect results](/cli-reference/job).
+
+## Select the work
+
+| Option | Meaning | Default |
+| --- | --- | --- |
+| `-d`, `--dataset <name[@version]>` | Dataset to evaluate. Repeat for more datasets. | Required, unless in config. |
+| `-a`, `--agent <name[@version]>` | Built-in or registered agent harness. | Required, unless in config. |
+| `-m`, `--model <name>` | Model for the harness. Repeat for one combination per model. | Required, unless in config. |
+| `-i`, `--include-task-name <glob>` | Include matching tasks in every dataset. Repeatable. | All tasks. |
+| `-x`, `--exclude-task-name <glob>` | Exclude matching tasks after inclusion. Repeatable. | None. |
+| `-l`, `--n-tasks <n>` | Cap tasks per dataset, after filters. | No cap. |
+| `-k`, `--n-attempts <n>` | Attempts per task and agent/model combination. | `1` |
+| `-n`, `--n-concurrent <n>` | Parallel trials, from `1` to `150`. | `4` |
+
+A bare dataset name selects its active version. Pin `name@version` for a repeatable selection.
+
+## Save a configuration
+
+Use a YAML or JSON file when a job has several agents or per-dataset settings.
+
+```yaml job.yaml
+job_name: hello-world-check
+datasets:
+  - name: harbor-examples
+    version: "1.0"
+    task_names: [hello-world]
+agents:
+  - name: codex
+    model_name: gpt-5.6-luna
+n_attempts: 1
+n_concurrent_trials: 4
+max_trial_spend_usd: 0.30
+retry:
+  max_retries: 0
+```
+
+```bash Run or inspect
+evolve run -c job.yaml --print-config
+evolve run -c job.yaml --watch
+```
+
+`--print-config` prints the request without creating a job or uploading local skills. It does not resolve catalog names or fill every server default. Inline secret values appear in this output.
+
+### How flags override the file
+
+| Flag | What it replaces |
+| --- | --- |
+| `-d` | The entire dataset list. |
+| `-a` and `-m` | The entire agent list. Supply both. |
+| `-i`, `-x`, `-l` | That field on every dataset selector. |
+| `--effort`, `--preset` | That field on every agent combination. |
+| `--ak` | Matching keys inside each agent's `kwargs`. |
+| `--skill` | Every agent's skills list. |
+| `--secret` / `--secret-inline` | The complete secret attachment list. |
+| Retry or analysis options | Only the named field inside `retry` or `analyze`. |
+
+Other flags override their matching field. Use `--org` or `auth org use` for organization selection; the current CLI does not retain `org` from the job file.
+
+Quote version strings in YAML, for example `version: "1.10"`. Config validation rejects unknown fields and duplicate keys before submission.
+
+## All other options
+
+### Job, organization, and sandbox
+
+| Option | Meaning |
+| --- | --- |
+| `--job-name <name>` | Job label. Generated when omitted. |
+| `--org <name>` | Organization to use. Otherwise use the saved CLI default, then your personal organization. `--org personal` overrides a saved team default. |
+| `-e`, `--env <provider>` | Requested sandbox provider: `daytona` (default), `e2b`, or `modal`. |
+| `--system-log` | Record the sandbox's system log. Off by default. |
+
+Evolve checks each task's requirements. A task may run on another compatible provider; inspect its trial for the provider actually used. See [Sandboxes](/core-concepts/sandboxes).
+
+### Agent settings and skills
+
+These options apply to every agent combination.
+
+| Option | Meaning |
+| --- | --- |
+| `--effort <value>` | Reasoning effort supported by the selected harness and model. |
+| `--preset <name>` | Supported settings preset: `no-internet` or `pinned-context`. |
+| `--ak <key=value>`, `--agent-kwarg <key=value>` | Agent setting. Repeatable. `config` accepts a local JSON/TOML file or inline JSON object. |
+| `--skill <ref>`, `--skills <ref>` | Skill reference or local directory. Repeatable. |
+
+```bash
+evolve run -c job.yaml --effort high --ak config=./codex.toml
+evolve run -c job.yaml --skill ./my-skill
+```
+
+Skills accept `skills.sh/owner/repo[/skill]`, `org/repo[@ref]`, a Git URL, `upload:<id>`, or `name:<skill-name>`. Local directories upload before the job starts.
+
+Unsupported effort, presets, or settings are refused. See [Agents](/core-concepts/agents) and [Skills](/core-concepts/skills).
+
+### Secrets and verifier environment
+
+| Option | Meaning |
+| --- | --- |
+| `--secret <NAME[@LABEL][=ENVNAME]>` | Attach a stored secret to agent runs. Repeatable. `@LABEL` selects a row; `=ENVNAME` renames the environment variable. |
+| `--secret-inline <NAME[@LABEL]:DELIVERY=VALUE>` | Store a secret and attach it. Evaluation jobs require `direct` delivery. Repeatable. |
+| `--verifier-env <KEY=VALUE>`, `--ve <KEY=VALUE>` | Verifier overrides: `REWARDKIT_JUDGE` and `REWARDKIT_MODEL`. Repeatable. |
+
+Store sensitive values with [`evolve secrets set`](/cli-reference/secrets), then attach them by name.
+
+```bash
+evolve run -c job.yaml --secret GITHUB_TOKEN
+```
+
+### Spend and automatic retries
+
+| Option | Meaning | Default |
+| --- | --- | --- |
+| `--max-trial-spend <usd>` | Agent model-spend cap per trial attempt. Must be greater than zero. | Platform default, normally `$200`. |
+| `-r`, `--max-retries <n>` | Additional attempts after eligible infrastructure errors. `0` disables these retries. | Platform default, normally `2`. |
+| `--retry-include <exception>` | Retry only these exception types. Repeatable. | Any type not excluded. |
+| `--retry-exclude <exception>` | Never retry these exception types. Repeatable; takes priority over include. | Built-in exclusions. |
+
+A low score does not trigger an infrastructure retry. Each retry has the full trial cap. Capacity waits are separate from this retry setting.
+
+See [Jobs](/core-concepts/jobs) for the retry and spend rules.
+
+### Analyze traces as trials finish
+
+| Option | Meaning |
+| --- | --- |
+| `--analyze` | Enable analysis with the platform defaults. |
+| `--analyze-model <name>` | Analyzer model. |
+| `--analyze-rubric <path>` | TOML, YAML, or JSON rubric. |
+| `--analyze-prompt <path>` | Replacement prompt file. |
+| `--analyze-provider <provider>` | Analyzer sandbox provider. |
+| `--analyze-effort <value>` | Analyzer reasoning effort. |
+
+Any `--analyze-*` option enables analysis. Read the current defaults with `evolve analyze --show-defaults`.
+
+To analyze an existing job, use [`evolve analyze`](/cli-reference/analyze).
+
+### Timeouts
+
+Every multiplier must be greater than zero. A phase-specific value overrides the general multiplier for that phase.
+
+| Option | Timeout affected |
+| --- | --- |
+| `--timeout-multiplier <x>` | All task timeouts. Default `1.0`. |
+| `--agent-timeout-multiplier <x>` | Agent execution. |
+| `--verifier-timeout-multiplier <x>` | Verifier execution. |
+| `--agent-setup-timeout-multiplier <x>` | Agent installation/setup. |
+| `--environment-build-timeout-multiplier <x>` | Environment preparation. |
+
+Values below `1` shorten a timeout. The task definition is unchanged.
+
+### Configuration and output
+
+| Option | Meaning |
+| --- | --- |
+| `-c`, `--config <path>` | Load YAML or JSON job configuration. |
+| `--print-config` | Print the constructed request and exit. |
+| `--watch` | Follow events until the job settles. |
+| `-q`, `--quiet` | With watch, suppress intermediate events. |
+| `-y`, `--yes` | Accepted for compatibility; no effect. |
+
+With `--watch --json`, output is one JSON record per line: `job.created`, events, then `job.final`. Quiet mode keeps the initial and final records.
+
+[Global options](/cli-reference/index#global-options) apply. Next, [inspect the job](/cli-reference/job).

package/skills/evolve-evals/references/cli-reference/secrets.md

@@ -0,0 +1,77 @@
+---
+title: "evolve secrets"
+description: "Store environment secrets and attach them to evaluations by name."
+---
+
+Store a value once, then attach its name to a job. Reads return metadata, never the stored value.
+
+```bash
+printf %s "$GITHUB_TOKEN" | evolve secrets set GITHUB_TOKEN \
+  --delivery brokered \
+  --allowed-host api.github.com \
+  --allowed-path-prefix / \
+  --allowed-method GET
+```
+
+Piping the value keeps it out of the command's arguments.
+
+## Choose delivery
+
+| Mode | What enters the sandbox |
+| --- | --- |
+| `brokered` | A reference used through the credential proxy. The stored value stays outside the sandbox. |
+| `direct` | The raw value as an environment variable. |
+
+Brokered secrets use the allowed-host, path, and method constraints. See [Secrets](/core-concepts/secrets) for delivery behavior.
+
+## Store a secret
+
+```bash
+printf %s "$SERVICE_TOKEN" | evolve secrets set SERVICE_TOKEN --delivery direct
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--value <value>` | Value to store. If omitted, read piped stdin. One trailing newline is removed from stdin. |
+| `--label <label>` | Row label under this name. Default `default`. |
+| `--delivery <brokered\|direct>` | Required delivery mode. |
+| `--allowed-host <host>` | Allowed hostname or wildcard. Repeatable. |
+| `--allowed-path-prefix <path>` | Allowed URL path prefix. Repeatable. |
+| `--allowed-method <method>` | Allowed HTTP method. Repeatable. |
+
+Restating the same value can update delivery or scoping. A different value under the same name and label is refused with `secret_exists`; use a new label or delete the old row first.
+
+## Attach it to a job
+
+```bash
+evolve run -c job.yaml --secret GITHUB_TOKEN
+evolve run -c job.yaml --secret SERVICE_TOKEN@staging=APP_TOKEN
+```
+
+The second example selects label `staging` and exposes it under `APP_TOKEN`. See [Run options](/cli-reference/run) for `--secret` and `--secret-inline`.
+
+## List metadata
+
+```bash
+evolve secrets list
+evolve secrets list --json
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--columns <keys\|all\|help>` | Select metadata columns. |
+| `-q`, `--quiet` | Print names, with `:label` for non-default labels. |
+| `--no-trunc` | Keep full terminal table cells. |
+| `--no-headers` | Omit piped TSV headers. |
+
+There are no pagination flags for this list.
+
+## Delete
+
+```bash
+evolve secrets delete SERVICE_TOKEN --label staging
+```
+
+`--label <label>` selects a row when a name has multiple labels. Deletion also revokes runtime grants tied to that row. This command has no confirmation prompt.
+
+[Global options](/cli-reference/index#global-options) apply.

package/skills/evolve-evals/references/cli-reference/session.md

@@ -0,0 +1,56 @@
+---
+title: "evolve session"
+description: "Inspect and share the sessions recorded by managed-agent SDK runs."
+---
+
+Sessions come from managed-agent SDK runs. They are separate from evaluation jobs and trials.
+
+```bash
+evolve session list
+evolve session show "$SESSION_ID"
+```
+
+Set `$SESSION_ID` to an ID from the list. These commands inspect recorded sessions; they do not start an agent. To create a session, follow the [agent SDK manual](https://github.com/evolving-machines-lab/evolve/blob/main/docs-agents/index.md).
+
+## Filter the list
+
+```bash
+evolve session list --state ended --tag-prefix qa- --scope org
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--scope <my\|shared\|org>` | Records to list. Default `my`. |
+| `--state <live\|ended>` | Select live or ended sessions. |
+| `--agent <name>` | Select one agent harness. |
+| `--tag-prefix <prefix>` | Select tags beginning with this text. |
+
+Shared [list options](/cli-reference/index#list-options) also apply: `--limit`, `--cursor`, `--columns`, `--quiet`, `--no-trunc`, `--no-headers`.
+
+## Share a session
+
+The creator can share by unlisted link or email.
+
+```bash
+evolve session share "$SESSION_ID" --link
+evolve session share "$SESSION_ID" --email colleague@example.com
+evolve session shares "$SESSION_ID"
+```
+
+| Option for `share` and `unshare` | Meaning |
+| --- | --- |
+| `--link` | Enable or disable the unlisted link. |
+| `--email <address>` | Add or remove access for this address. Repeatable. |
+
+Supply at least one. Email sharing sends the recipient a link. A session share includes the session, transcript, and trace file.
+
+## Remove access
+
+```bash
+evolve session unshare "$SESSION_ID" --link
+evolve session unshare "$SESSION_ID" --email colleague@example.com
+```
+
+Revoking a link disables it. A later link share creates a new link.
+
+[Global options and ID prefixes](/cli-reference/index) apply. `sessions` is an alias of `session`.

package/skills/evolve-evals/references/cli-reference/skill.md

@@ -0,0 +1,52 @@
+---
+title: "evolve skill"
+description: "Upload skills for evaluated agents and reuse them by reference."
+---
+
+Upload a skill folder, then attach it to a job.
+
+```bash
+evolve skill upload ./my-skill
+evolve run -c job.yaml --skill name:my-skill
+```
+
+This singular `skill` group manages uploaded content. To read the CLI's bundled manual, use [`evolve skills`](/cli-reference/skills).
+
+## Upload
+
+```bash
+evolve skill upload ./my-skill --org acme
+```
+
+`--org <name>` selects the owning organization. Without it, the CLI uses its saved default, then your personal organization.
+
+A directory containing multiple skills can return multiple upload records. Each record has two ways to reference it:
+
+| Reference | Use when… |
+| --- | --- |
+| `upload:<id>` | You want this exact upload. |
+| `name:<skill-name>` | You want the current upload under that name when the job is created. |
+
+Organization members can reference uploaded skills in their jobs. Only the creator can delete an upload.
+
+## List and inspect
+
+```bash
+evolve skill list --scope org
+evolve skill show name:my-skill
+evolve skill show "$SKILL_ID" --json
+```
+
+`$SKILL_ID` comes from upload or list output. `show` includes metadata and `SKILL.md`.
+
+`skill list` accepts `--scope <my|shared|org>` and the shared [list options](/cli-reference/index#list-options).
+
+## Delete
+
+```bash
+evolve skill delete "$SKILL_ID"
+```
+
+A skill referenced by a running job is refused with `skill_in_use`. Past jobs keep their resolved skill records. This command has no confirmation prompt.
+
+[Global options](/cli-reference/index#global-options) apply. See [Skills](/core-concepts/skills) for supported sources and how jobs resolve them.

package/skills/evolve-evals/references/cli-reference/skills.md

@@ -0,0 +1,85 @@
+---
+title: "evolve skills"
+description: "Read the bundled manual and install its small entry point for coding agents."
+---
+
+The manual ships with the CLI. An agent can read its index, then load just the page it needs.
+
+```bash
+evolve skills get evals
+evolve skills get evals cli-reference/run
+```
+
+```text
+Installed pointer: evolve
+  ↓
+Documentation index
+  evolve skills get evals
+  ↓
+One focused page
+  evolve skills get evals PAGE
+```
+
+These commands read local package files; they do not call the Evolve API.
+
+## List the bundled skills
+
+```bash
+evolve skills
+evolve skills list --json
+```
+
+| Skill | Purpose |
+| --- | --- |
+| `evals` | Managed evaluations: concepts, CLI, APIs, and SDKs. |
+| `create-task` | Author a Harbor-format task. |
+| `rewardkit` | Write a verifier with Reward Kit. |
+| `create-adapter` | Convert a benchmark into tasks. |
+| `publish` | Publish task datasets or import completed results. |
+
+The root `evolve` pointer is available by explicit name but hidden from the list. The managed-agents SDK skill is separate; it is not served by this command.
+
+## Read a skill or page
+
+```bash
+evolve skills get create-task
+evolve skills get create-task rewardkit
+evolve skills get evals core-concepts/tasks
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--full` | Include all files under the skill's references and templates. |
+| `--all` | Read every listed skill without supplying names. |
+
+`get <skill> <page>` accepts the page path with or without `.md`/`.mdx`. It cannot combine with `--full`. `--all` cannot combine with skill names.
+
+Prefer the index and focused pages. Use `--full` when the complete reference is needed.
+
+## Find files on disk
+
+```bash
+evolve skills path
+evolve skills path evals
+```
+
+The optional skill name selects its folder. `EVOLVE_SKILLS_DIR` can point to a different skills directory for local development.
+
+## Install the pointer
+
+```bash
+evolve skills install
+evolve skills install --target codex
+```
+
+Only the small `evolve/SKILL.md` pointer is installed. The full manual stays in the CLI package.
+
+| Option | Meaning |
+| --- | --- |
+| `--target <name>` | `claude`, `codex`, `cursor`, `copilot`, `gemini`, `opencode`, `agents`, or `all`. Default `all`. |
+| `--path <dir>` | Your own skills directory instead of a named target. |
+| `--force` | Replace an installed pointer whose contents differ. |
+
+`all` installs into agent homes that already exist. A named target may create its directory. Existing identical pointers are left alone; differing content requires `--force`.
+
+`--target` and `--path` cannot be combined. [Global options](/cli-reference/index#global-options), including JSON output, apply.