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.

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

Next

Build your first agent

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