---
name: clyc-cli
description: Use when working with the CLYC CLI or CLI API for project files, videos, images, folders, uploads, downloads, versions, comments, share links, reports, clients, tracker checks, or production-safe CLYC automation.
---

# CLYC CLI

Use the official `clyc` CLI first. Use raw `/api/cli/v1` requests only when the CLI does not expose the needed operation or the user explicitly asks for HTTP/API details.

## First checks

1. Check whether `clyc` is installed with `command -v clyc`. If it is missing, use the app-served installer: `curl -fsSL https://app.clyc.io/api/developer/cli/install.sh | sh`.
2. Check skill freshness with `clyc skills status`. If it is stale or missing, run `clyc skills update --target all`.
3. Verify the configured API and identity with `clyc auth status` and `clyc me`.
4. If no token is configured, direct the user to CLYC Personal Account -> API Tokens. Prefer `clyc auth login --api-url <url> --token <token>` or environment variables over placing tokens in chat history.
5. Confirm the target account, project, item, folder, version, or share before mutating production data.
6. When the user provides text, a page, or a link from another tool, first look for CLYC URLs or IDs. Treat those CLYC references as the source of truth before searching by name.
7. Return JSON IDs, names, and URLs that the user needs for the next step.

## Guardrails

- Treat `clyc_` API tokens as secrets. Do not print, log, commit, or echo full tokens.
- Do not bypass CLYC app permissions. The API token inherits the issuing user's current product permissions.
- Prefer soft delete unless the user explicitly asks for permanent delete.
- Ask for confirmation before permanent delete, disabling a share used by others, regenerating a public share token, or bulk-moving/deleting items unless the request already makes that intent clear.
- For uploads and downloads, preserve filenames when possible and verify size or checksum when the user cares about exact file integrity.
- For comments on versioned items, use `--version-id` when a version id is known. Use `--version-number` only after listing versions if ordering might have changed.

## Common workflow

1. Identify context: `clyc me`, `clyc accounts list`, `clyc projects list`.
2. Locate files/folders: `clyc files list` or `clyc files search`.
3. Perform the smallest CLI action that satisfies the request.
4. Re-read the changed resource and summarize the final state.

## CLYC references from external tools

When a task starts from Notion, Slack, email, a browser page, a report, a client tracker, or any other external system, first extract CLYC links and IDs from that source. Do not assume the external system's page type is the workflow. The useful signal is the CLYC reference inside it.

If the user's requested action is clear and the command accepts the CLYC reference, run that command directly. For example, when the user asks whether a known video/review link has comments, use `clyc comments list "<clyc-url>"` directly; do not resolve first as a required extra step.

Use `clyc resolve "<clyc-url-or-id>"` when you need to identify what a CLYC link points to, inspect a folder or collection preview, choose the next command, or explain the target. For folder and collection links, resolve first unless the URL points to a specific item.

Commands that accept CLYC URLs directly include `clyc files get`, `clyc files download`, `clyc files versions`, `clyc comments list`, `clyc comments add`, `clyc shares list`, `clyc projects get`, and `clyc files list` for project/folder URLs. Only fall back to broad `clyc projects list`, `clyc files list`, or `clyc files search` when no usable CLYC URL or ID is available.

## References

- Use [references/commands.md](references/commands.md) for the command map and endpoint catalog.
- Use [references/safety.md](references/safety.md) for token handling, destructive actions, and production checks.