.\"
.\" Copyright (c) 2021-2022 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd June 30, 2021-2022
.Dt SCICTL 8
.Os
.\" NAME
.Sh NAME
.Nm scictl
.Nd command line client to scid
.\" SYNOPSIS
.Sh SYNOPSIS
.\" job-add
.Nm
.Cm job-add
.Ar project
.Ar tag
.\" job-todo
.Nm
.Cm job-todo
.Ar worker
.\" project-add
.Nm
.Cm project-add
.Ar name
.Ar desc
.Ar url
.Ar script
.\" project-info
.Nm
.Cm project-info
.Ar name
.\" project-list
.Nm
.Cm project-list
.\" project-update
.Nm
.Cm project-update
.Ar name
.Ar key
.Ar value
.\" worker-add
.Nm
.Cm worker-add
.Ar name
.Ar desc
.\" worker-list
.Nm
.Cm worker-list
.\" DESCRIPTION
.Sh DESCRIPTION
The
.Nm
utility is a command line client that connects to
.Xr scid 8
daemon. It is best used in conjunction with automated programs (such as cron)
and SCM integration to add new jobs to execute. It is also used as
administrative utility to create projects and workers.
.Pp
The following options are available
.Em before
the command name:
.Bl -tag
.It Fl k Ar key
Set the API authentication to
.Ar key .
.It Fl u
Set the
.Ar url
for connecting to
.Xr scid 8 .
You can specify a scheme using
.Dq http://
or
.Dq https:// .
Default:
.Dq localhost .
.El
.Pp
It is part of the
.Xr sci 7
continuous integration framework.
.\" COMMANDS
.Sh COMMANDS
All commands are designed to return a human readable format but is guaranteed to
stay compatible across new versions. It can be used in scripts as well.
.Bl -tag -width project-update
.\" job-add
.It Cm job-add
Create a new job for the given
.Ar project
using the user arbitrary
.Ar tag
identifier.
.\" job-todo
.It Cm job-todo
List jobs that must be performed by the given
.Ar worker
name. Jobs that were created earlier than the worker will not be listed to
avoid evaluating a possible high number of jobs.
.\" project-add
.It Cm project-add
Create a new project with
.Ar name ,
a user description set with
.Ar desc ,
an arbitrary website
.Ar url ,
and a script code to execute specified by file
.Ar script .
If the
.Ar script
argument is set to
.Dq -
the standard input is read instead.
.\" project-info
.It Cm project-info
Get the detailed information, including the script code from
.Ar project .
.\" project-list
.It Cm project-list
List all projects, excluding the script code.
.\" project-update
.It Cm project-update
Update an existing
.Ar project
by setting its new fields.
.Pp
The
.Ar key
argument should be one of the argument name is similar to the
.Cm project-add
command. For example, to update the description of a project one should
specify
.Dq desc
as
.Ar name
argument and a new description as
.Ar key .
.\" worker-add
.It Cm worker-add
Create a new worker with
.Ar name
user identifier and an arbirary
.Ar desc
description.
.\" worker-list
.It Cm worker-list
List all workers present on the system. It does not indicate if those workers
are actually running.
.El
.\" ENVIRONMENT
.Sh ENVIRONMENT
The following environment variables affects
.Nm :
.Bl -tag
.It Ev SCI_API_URL
Points to a HTTP URL where
.Nm scid
is running. Must start with a HTTP scheme such as
.Dq http
or
.Dq https .
.It Ev SCI_API_KEY
Secret API key to perform requests.
.El
.\" EXAMPLES
.Sh EXAMPLES
Add a new worker named OpenBSD with identifier openbsd
.Bd -literal -offset indent
$ scictl worker-add openbsd OpenBSD
.Ed
.Pp
Add a project hello that executes a script shell.
.Bd -literal -offset indent
$ scictl project add hello "Hello World" http://hello.org hello.sh
.Ed
.Pp
Add a new job for the project hello with as argument
.Dq world
.Bd -literal -offset indent
$ scictl job-add hello world
.Ed
.Pp
Update the project hello with new description and new code
.Bd -literal -offset indent
scictl project-update example desc "Hello World v2""
scictl project-update example script hello2.sh
.Ed
.\" SEE ALSO
.Sh SEE ALSO
.Xr sci 7 ,
.Xr scid 8 ,
.Xr sciworkerd 8