> ## Documentation Index > Fetch the complete documentation index at: https://docs.cycls.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Every cycls command with its arguments, flags, defaults and output: run, deploy, shell, ls, rm, logs, cost, sql, volume, init, version. The CLI mirrors the Python API. `run` is local, `--remote` is cloud, `deploy` freezes. ```bash theme={null} pip install cycls cycls version ``` **Authentication:** set `CYCLS_API_KEY` in the environment or a `.env` file, or assign `cycls.api_key` in Python. `CYCLS_BASE_URL` overrides the default `https://api.cycls.ai`. **Target syntax:** every command that takes a file accepts `path.py`, or `path.py::name` to select one of several decorated objects in that file. Each command imports the file, so keep it free of top-level side effects such as a bare `.run()` or `.deploy()` call. ## Command summary | Command | Purpose | | -------------------------------------------- | ------------------------------- | | [`cycls init [name]`](#cycls-init) | scaffold a starter agent file | | [`cycls run `](#cycls-run) | development loop, rerun on save | | [`cycls deploy `](#cycls-deploy) | build and publish | | [`cycls shell `](#cycls-shell) | bash inside the built image | | [`cycls ls`](#cycls-ls) | list deployments | | [`cycls rm `](#cycls-rm) | delete a deployment | | [`cycls logs `](#cycls-logs) | fetch or tail logs | | [`cycls cost `](#cycls-cost) | aggregate model spend | | [`cycls sql [query]`](#cycls-sql) | SQL over logs and billing | | [`cycls volume `](#cycls-volume) | manage persistent storage | | [`cycls version`](#cycls-version) | print the installed version | ## cycls init Scaffold a starter agent at `.py`. ```bash theme={null} cycls init notes # Created notes.py # # Next steps: # cycls run notes.py # run locally in Docker # cycls deploy notes.py # deploy to production ``` | Argument | Required | Default | | -------- | -------- | ---------- | | `name` | no | `my_agent` | The command fails if the file already exists. ## cycls run Watch the file and any copied files, and rerun on every save. ```bash theme={null} cycls run app.py # local Docker cycls run app.py --remote # cloud cycls run simulate.py --n 1000 # bind arguments to the signature ``` | Flag | Meaning | | ------------------ | ------------------------------------------- | | `--remote` | run in the cloud instead of local Docker | | `-- ` | bind to the target's parameter of that name | Argument binding rules: an annotated parameter converts through its annotation, so `n: int` receives an int. An unannotated parameter is parsed as a Python literal, so `--data "[1,2]"` becomes a list. Anything else stays a string. Behavior by target: * **Functions** rerun locally in Docker, or on a warm cloud executor with `--remote`. Remote `print()` output streams back live. * **Apps and agents** serve on `localhost:8080`, or on `https://dev-.cycls.ai` with `--remote`, where each save hot swaps the running application. A save during a run queues the next run rather than killing the current one. With `@cycls.local_entrypoint`, the entrypoint always runs locally and the verbs inside it decide where work happens, so `--remote` does not apply and is rejected. ## cycls deploy Build and publish to Cycls Cloud. ```bash theme={null} cycls deploy notes.py # Checking 'notes'... # Deploying 'notes'... # [BUILDING] ... # [DEPLOYING] ... # [DONE] https://notes.cycls.ai ``` The deployment name comes from the decorator's `name=` or the function name. Redeploying a name updates it in place. See [Deploy](/ship/deploy) for sizing, limits and the isolation boundary. ## cycls shell Open an interactive bash session inside the target's built image, the same environment `run` and `deploy` execute in. ```bash theme={null} cycls shell examples/c.py # Entering cycls/triangle:730f149a (exit to leave) root@a1b2c3:/app# gcc --version ``` Builds or reuses the cached image, drops you in `/app`, and cleans up on exit. ## cycls ls ```bash theme={null} cycls ls # super-stage https://super-stage.cycls.ai [us-central1] 2026-05-15T18:14 # notes https://notes.cycls.ai [us-central1] 2026-05-10T09:00 ``` Development artifacts appear here too: `exec-*` are function executors and `dev-*` are app dev services. Both scale to zero and cost nothing while idle. `cycls rm` removes them. ## cycls rm ```bash theme={null} cycls rm notes # asks for confirmation cycls rm notes -y # skips confirmation ``` | Flag | Meaning | | ----------- | ---------------------------- | | `-y, --yes` | skip the confirmation prompt | Deleting a deployment detaches its volumes and leaves their data intact. Redeploying the same name reattaches them. ## cycls logs ```bash theme={null} cycls logs my-agent cycls logs my-agent -f cycls logs my-agent -s 30m cycls logs my-agent -q 'jsonPayload.error_id="abc12345"' ``` | Flag | Meaning | Default | | -------------- | ------------------------------------------- | ----------------- | | `-f, --follow` | tail, polling every 2 seconds | off | | `-s, --since` | window: `30m`, `24h`, `7d` | most recent batch | | `-q, --query` | structured filter passed to the log backend | none | Field reference and examples: [Logs, cost and SQL](/ship/observability). ## cycls cost ```bash theme={null} cycls cost my-agent # my-agent $0.027126 (4 turns, 24h) ``` | Flag | Meaning | Default | | ----------------------- | --------------------------------------------------------- | ------- | | `-s, --since` | `30m`, `24h`, `7d` | `24h` | | `-m, --month [YYYY-MM]` | a calendar month, current if no value. Excludes `--since` | off | | `-b, --by` | group by `user`, `chat` or `model` | none | Requires `cycls.LLM().price(...)` on the agent. Without it, spend reports as zero. ## cycls sql ```bash theme={null} cycls sql 'SELECT COUNT(*) FROM logs' cycls sql -f query.sql cat query.sql | cycls sql cycls sql 'SELECT ...' --json ``` | Flag | Meaning | Default | | ------------ | ---------------------------- | ------------------------------------ | | `-f, --file` | read the query from a file | none | | `--format` | `table`, `json` or `csv` | table on a terminal, json when piped | | `--json` | shortcut for `--format json` | | Pass `-` as the query to force reading stdin. Tables and example queries: [Logs, cost and SQL](/ship/observability). ## cycls volume ```bash theme={null} cycls volume create training-data cycls volume ls cycls volume ls training-data models/ cycls volume put training-data ./model.bin models/model.bin cycls volume get training-data outputs/result.parquet . cycls volume rm training-data models/old.bin cycls volume delete training-data -y ``` | Subcommand | Arguments | Purpose | | ---------- | --------------------- | ---------------------------------------------------- | | `create` | `name` | create a volume | | `ls` | `[name] [path]` | list volumes, or contents under a prefix | | `put` | `name local [remote]` | upload a file. Remote path defaults to the file name | | `get` | `name remote [local]` | download a file | | `rm` | `name path` | remove one file | | `delete` | `name [-y]` | delete the volume and its data | `put` and `get` talk to storage directly, so transfers do not pass through the API and file size is effectively unlimited. `delete` refuses while any deployment has the volume attached and names them in the error. Deleted volumes stay recoverable for seven days. ## cycls version ```bash theme={null} cycls version # cycls 0.0.2.141 ``` ## Next A guided build from an empty directory to a deployed URL.