CLI reference

The CLI mirrors the Python API. run is local, --remote is cloud, deploy freezes.

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]`	scaffold a starter agent file
`cycls run <file>`	development loop, rerun on save
`cycls deploy <file>`	build and publish
`cycls shell <file>`	bash inside the built image
`cycls ls`	list deployments
`cycls rm <name>`	delete a deployment
`cycls logs <name>`	fetch or tail logs
`cycls cost <name>`	aggregate model spend
`cycls sql [query]`	SQL over logs and billing
`cycls volume <subcommand>`	manage persistent storage
`cycls version`	print the installed version

cycls init

Scaffold a starter agent at <name>.py.

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.

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
`--<name> <value>`	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-<name>.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.

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 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.

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

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

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

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.

cycls cost

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

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.

cycls volume

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

cycls version
# cycls 0.0.2.141

Build your first agent

A guided build from an empty directory to a deployed URL.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

CLI reference

Command summary

cycls init

cycls run

cycls deploy

cycls shell

cycls ls

cycls rm

cycls logs

cycls cost

cycls sql

cycls volume

cycls version

Next

Build your first agent

​Command summary

​cycls init

​cycls run

​cycls deploy

​cycls shell

​cycls ls

​cycls rm

​cycls logs

​cycls cost

​cycls sql

​cycls volume

​cycls version

​Next

Build your first agent

Command summary

cycls init

cycls run

cycls deploy

cycls shell

cycls ls

cycls rm

cycls logs

cycls cost

cycls sql

cycls volume

cycls version

Next