Skip to content

sys ​

sys.alert() ​

Display a dialog box.

python
sys.alert(text: str) -> str

Arguments ​

NameTypeDefaultDescription
textstrThe message to show.

Return ​

TypeDescription
strThe name of the button selected by the user.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    button = sys.alert("Test message.")
    sys.log(f"You pressed {button}.")

sys.execute() ​

Execute a shell command and get its output.

python
sys.execute(command: str) -> str

Arguments ​

NameTypeDefaultDescription
commandstrThe command to execute.

Return ​

TypeDescription
strThe output of command.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(sys.execute("whoami").strip())

sys.log() ​

Output any object to logs, logs can be viewed in the VS Code extension and also in "CatScript -> Settings -> Logs".

python
sys.log(object: object) -> None

Arguments ​

NameTypeDefaultDescription
objectobjectThe object to log.

Return ​

None

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(device.ip())

sys.open_url() ​

Open the resource at the specified URL.

TIP

You can obtain a list of supported settings URLs here.

python
sys.open_url(url: str) -> None

Arguments ​

NameTypeDefaultDescription
urlstrThe URL to open.

Return ​

None

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.open_url("https://catscript.app")
    sys.open_url("sms://12345")
    sys.open_url("prefs:root=WIFI")

sys.paste() ​

Paste text into the input box.

TIP

In the latest iOS system, when pasting, there will be a dialog box asking for permission. You can use the functions in the touch module to click the "Allow Paste" button.

python
sys.paste(text: str) -> None

Arguments ​

NameTypeDefaultDescription
textstrThe text to paste.

Return ​

None.

Example ​

python
from catscript import device, sys

if __name__ == "__main__":
  sys.paste(device.ip())

sys.copy() ​

Copy text to the clipboard without pasting it.

python
sys.copy(text: str) -> None

Arguments ​

NameTypeDefaultDescription
textstrThe text to copy.

Return ​

None.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.copy("hello")

sys.brightness() ​

Get the screen brightness.

python
sys.brightness() -> int

Arguments ​

None.

Return ​

TypeDescription
intBrightness from 0 to 100.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(sys.brightness())

sys.set_brightness() ​

Set the screen brightness.

python
sys.set_brightness(value: int, disable_auto: bool = False) -> None

Arguments ​

NameTypeDefaultDescription
valueintBrightness from 0 to 100.
disable_autoboolFalseWhether to disable auto-brightness permanently.

Return ​

None.

WARNING

Setting disable_auto=True changes a persistent system setting.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.set_brightness(80)

sys.volume() ​

Get the system volume.

python
sys.volume() -> int

Arguments ​

None.

Return ​

TypeDescription
intVolume from 0 to 100.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(sys.volume())

sys.set_volume() ​

Set the system volume.

python
sys.set_volume(value: int) -> None

Arguments ​

NameTypeDefaultDescription
valueintVolume from 0 to 100.

Return ​

None.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.set_volume(30)

sys.locked() ​

Check whether the device is locked.

python
sys.locked() -> bool

Arguments ​

None.

Return ​

TypeDescription
boolTrue if the device is locked.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(sys.locked())

sys.unlock() ​

Unlock the device.

python
sys.unlock(password: str = "") -> None

Arguments ​

NameTypeDefaultDescription
passwordstr""The lock-screen passcode, if the device has one.

Return ​

None.

WARNING

The passcode is stored in the script as plain text. This API is experimental and depends on a private system API.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.unlock()

sys.orientation_locked() ​

Check whether orientation lock is enabled.

python
sys.orientation_locked() -> bool

Arguments ​

None.

Return ​

TypeDescription
boolTrue if orientation lock is enabled.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(sys.orientation_locked())

sys.set_orientation_lock() ​

Enable or disable orientation lock.

python
sys.set_orientation_lock(on: bool) -> None

Arguments ​

NameTypeDefaultDescription
onboolTrue to lock, False to unlock.

Return ​

None.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.set_orientation_lock(True)

sys.assistive_touch_enabled() ​

Check whether AssistiveTouch is enabled.

python
sys.assistive_touch_enabled() -> bool

Arguments ​

None.

Return ​

TypeDescription
boolTrue if AssistiveTouch is enabled.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(sys.assistive_touch_enabled())

sys.set_assistive_touch() ​

Enable or disable AssistiveTouch.

python
sys.set_assistive_touch(on: bool) -> None

Arguments ​

NameTypeDefaultDescription
onboolTrue to enable, False to disable.

Return ​

None.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.set_assistive_touch(False)

sys.control_center_visible() ​

Check whether Control Center is visible.

python
sys.control_center_visible() -> bool

Arguments ​

None.

Return ​

TypeDescription
boolTrue if Control Center is visible.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.log(sys.control_center_visible())

sys.set_control_center() ​

Show or hide Control Center.

python
sys.set_control_center(on: bool) -> None

Arguments ​

NameTypeDefaultDescription
onboolTrue to show, False to hide.

Return ​

None.

TIP

Control Center has an opening/closing animation. Wait about one second before checking sys.control_center_visible().

Example ​

python
import time
from catscript import sys

if __name__ == "__main__":
    sys.set_control_center(True)
    time.sleep(1)
    sys.set_control_center(False)

sys.play_sound() ​

Plays a system sound.

TIP

You can obtain a list of system sound ids here.

python
sys.play_sound(id: int) -> None

Arguments ​

NameTypeDefaultDescription
idintThe id of system sound.

Return ​

None

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.play_sound(1005)

sys.toast() ​

Display a toast.

python
sys.toast(text: str, ms: int) -> None

Arguments ​

NameTypeDefaultDescription
textstrThe message to show.
msint1000The displayed time, in milliseconds.

Return ​

None.

Example ​

python
from catscript import sys

if __name__ == "__main__":
    sys.toast("Test", 3000)